write-that-shit-down

write-that-shit-down

A Claude Code plugin for capturing project decisions as immutable ADRs and maintaining a cross-session knowledge vault.

You forget why decisions were made. Future-you (and Claude) need that context. Write it down.

What it does

When you make a decision (vendor, library, schema, trade-off, hosting, security), this plugin prompts Claude to:

1. Write a dated, immutable ADR (Architecture Decision Record) under vault/decisions/
2. Update affected service / infra / db notes in the vault
3. Link the new ADR from vault/INDEX.md
4. At end of session, write vault/sessions/YYYY-MM-DD.md summarizing what changed

The vault is plain markdown with Obsidian-style wikilinks. Open it in Obsidian for the graph view, or read it as flat files. Either works.

Vault structure

vault/
├── INDEX.md                # entry point, link directory
├── _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, access control
├── decisions/              # YYYY-MM-DD-<slug>.md (immutable)
├── sessions/               # YYYY-MM-DD.md session notes
└── patterns/               # conventions, gotchas

Install (as a Claude Code plugin)

Inside Claude Code, add this repo as a marketplace and install:

/plugin marketplace add roshan-3/write-that-shit-down
/plugin install write-that-shit-down@write-that-shit-down

Or test locally without installing:

git clone https://github.com/roshan-3/write-that-shit-down.git
claude --plugin-dir ./write-that-shit-down

Activation

Once installed, Claude activates the plugin automatically when you:

• State a decision ("let's use X", "going with Y")
• Pick between alternatives
• Make a trade-off
• Add infra or restructure schema
• Close a session that changed architecture
• Ask "why did we..." about a past choice

Or trigger it explicitly:

• /write-that-shit-down:track to invoke the skill
• Say "write that down" / "log this decision" / "ADR this"
• Ask Claude to set up a vault

ADR format

ADRs follow the classic Context / Decision / Consequences / Alternatives shape. See skills/track/templates/_adr-template.md.

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

End-of-session protocol

If a session changed architecture, deps, hosting, or external services, before stopping:

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

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

Repo layout

write-that-shit-down/
├── .claude-plugin/
│   ├── plugin.json         # plugin manifest
│   └── marketplace.json    # single-plugin marketplace manifest
├── skills/
│   └── track/
│       ├── SKILL.md
│       └── templates/
│           ├── _adr-template.md
│           ├── _session-template.md
│           └── INDEX-template.md
├── README.md
└── LICENSE

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.

License

MIT.