Decide

Decide — Record Technical Decisions to Obsidian

Capture architectural and technical decisions with full context as ADR-lite (Architecture Decision Record) notes in the Obsidian vault. Each decision records the context, options considered, rationale, and trade-offs accepted.

Tools needed: Bash, Write, Read

Procedure

Follow these steps exactly. Do not skip steps or reorder them.

Step 1 — Read config

Run:

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
python3 -c '
import sys, os
import glob; sys.path.insert(0, max(glob.glob(os.path.expanduser("~/.claude/plugins/cache/*/obsidian-brain/*/hooks")), default="hooks"))
from obsidian_utils import load_config
c = load_config()
if not c.get("vault_path"):
    print("ERROR: vault_path not configured", file=sys.stderr)
    sys.exit(1)
print("VAULT=" + c["vault_path"])
print("SESS=" + c.get("sessions_folder", "claude-sessions"))
print("INS=" + c.get("insights_folder", "claude-insights"))
'

Parse each output line as KEY=VALUE, splitting on the first =.

If the file does not exist or is invalid JSON, tell the user:

Config not found. Please run /obsidian-setup first to configure your Obsidian vault.

Stop here if config is missing.

Step 2 — Validate vault access

Run:

test -d "$VAULT_PATH/$INSIGHTS_FOLDER" && test -w "$VAULT_PATH/$INSIGHTS_FOLDER" && echo "OK" || echo "FAIL"

If FAIL, tell the user:

The insights folder $VAULT_PATH/$INSIGHTS_FOLDER does not exist or is not writable. Run /obsidian-setup to fix this.

Stop here if FAIL.

Step 3 — Identify the decision

Check if the user provided an argument after /decide.

• With argument (e.g. /decide use Redis for rate limiting): Use the argument as the decision summary and analyze the conversation for supporting context around that decision.
• Without argument (bare /decide): Analyze the full conversation to identify the most recent or most significant architectural/technical decision made during the session. Present it to the user for confirmation:

Decision detected:

Is this the decision you want to record, or would you like to specify a different one?

Wait for confirmation before proceeding.

Step 4 — Structure the ADR-lite note

Analyze the conversation thoroughly and draft the decision note with these sections:

Context — 2-4 sentences explaining what problem or situation prompted this decision. What were the requirements or constraints?

Options Considered — A numbered list of alternatives that were discussed or could have been considered. For each option, include a brief description (1-2 sentences).

Decision — A clear statement of what was chosen. 1-3 sentences.

Rationale — Why this option was selected over the alternatives. What factors tipped the balance? 2-4 sentences.

Consequences — What trade-offs were accepted by making this decision. Include both positive outcomes and negative trade-offs. Bulleted list of 2-5 items.

Step 5 — Auto-generate topic tags

Based on the decision content, generate 1-3 topic tags. Tags should be lowercase, hyphenated, and specific. Examples:

• claude/topic/caching-strategy
• claude/topic/database-choice
• claude/topic/api-design
• claude/topic/auth-architecture

Step 6 — Show preview and ask for edits

Present the full note to the user including frontmatter:

---
type: claude-decision
date: YYYY-MM-DD
created_at: <ISO-8601-UTC>
source_session: <current-session-id>
source_session_note: "[[<session-note-filename>]]"
project: <project-name>
status: active
tags:
  - claude/decision
  - claude/project/<project-name>
  - claude/topic/<auto-generated-topic-1>
  - claude/topic/<auto-generated-topic-2>
---

# <Decision Title>

## Context

<What problem prompted this decision>

## Options Considered

1. **<Option A>** — <brief description>
2. **<Option B>** — <brief description>
3. **<Option C>** — <brief description>

## Decision

<What was chosen>

## Rationale

<Why this option won>

## Consequences

- <positive or negative trade-off>
- <positive or negative trade-off>
- <positive or negative trade-off>

Where:

• YYYY-MM-DD is today's date

• <ISO-8601-UTC> is the current UTC timestamp at second precision. Get it via:

  python3 -c 'from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat(timespec="seconds"))'
  

  Example: 2026-04-24T18:42:11+00:00

• <current-session-id> and <session-note-filename> are derived together. Get session context via the shared helper:

  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
  python3 -c '
  import sys, os
  import glob; sys.path.insert(0, max(glob.glob(os.path.expanduser("~/.claude/plugins/cache/*/obsidian-brain/*/hooks")), default="hooks"))
  from obsidian_utils import load_config, get_session_context
  c = load_config()
  ctx = get_session_context(c["vault_path"], c.get("sessions_folder", "claude-sessions"))
  print("SID=" + ctx["session_id"] + " HASH=" + ctx["hash"] + " PROJECT=" + ctx["project"] + " SESSION_NOTE=" + ctx["session_note_name"])
  '
  

  Parse the output to get SESSION_ID, HASH, PROJECT, and SESSION_NOTE.

  Important: If SESSION_ID is unknown, use unknown for source_session and omit source_session_note entirely.

• <project-name> is the PROJECT value from get_session_context() (lowercased, hyphenated basename of cwd)

• The source_session_note field creates an Obsidian backlink to the source session note

Ask the user:

Preview above. Would you like to:

• save as-is
• edit tags — add or remove tags
• edit content — tell me what to change
• cancel — discard this decision

Wait for the user's response. Apply any requested edits and show the updated preview. Repeat until the user says save or cancel.

If cancel, stop here.

Step 7 — Generate filename

Construct the filename from these parts:

1. Date: YYYY-MM-DD (today)
2. Slug: The decision title, lowercased, spaces replaced with hyphens, non-alphanumeric characters (except hyphens) removed, truncated to 50 characters
3. Hash: 4-character hex hash derived from the current timestamp: date +%s | md5 | cut -c29-32 (macOS) or date +%s | md5sum | cut -c1-4 (Linux). Do NOT use tail -c 4 — it counts the trailing newline as a byte and returns only 3 visible characters.
4. Suffix: -decision

Final filename: YYYY-MM-DD-<slug>-<hash>-decision.md

Example: 2026-04-04-use-redis-for-rate-limiting-a3f2-decision.md

Step 8 — Write the note

Run:

mkdir -p "$VAULT_PATH/$INSIGHTS_FOLDER"

Then use the Write tool to write the full note (frontmatter + body) to:

$VAULT_PATH/$INSIGHTS_FOLDER/YYYY-MM-DD-<slug>-<hash>-decision.md

Then set permissions:

chmod 644 "$VAULT_PATH/$INSIGHTS_FOLDER/YYYY-MM-DD-<slug>-<hash>-decision.md"

Step 9 — Confirm

Print:

Decision recorded!

• File: $VAULT_PATH/$INSIGHTS_FOLDER/<filename>
• Status: active
• Tags: claude/decision, claude/project/<name>, claude/topic/<topic1>, ...
• Open in Obsidian to view, link to other notes, or update the status later.

To revisit past decisions, search for type: claude-decision in your vault or check the Active Decisions section of the sessions-overview dashboard.