Decision Log
Annotate code with Architecture Decision Records (ADRs) — stored locally, surfaced on hover.
The Problem
Code exists, but why it was written that way is lost forever. Git blame shows who wrote it, never why. Junior developers re-litigate decisions. Reviewers ask the same questions repeatedly.
What It Does
Decision Log lets you attach Architecture Decision Records directly to lines or functions in your code. Decisions are stored as JSON files in a .decisions/ folder and appear as hover tooltips and gutter highlights in the editor.
![Decision Log hover showing decision title and rationale on annotated code]
Features
- Add decisions via right-click context menu on any selection
- Hover tooltip shows the decision title, rationale, author, and date on annotated lines
- Overview ruler marks annotated lines in the scrollbar
- View all decisions in a searchable panel grouped by file
- Delete decisions from hover tooltip or the all-decisions panel
- Persisted locally in
.decisions/ — commit it to share with your team
Getting Started
- Open any file in your workspace
- Select the line(s) or function you want to annotate
- Right-click → Decision Log: Add Decision
- Fill in the title and rationale in the panel that opens
- Click Save Decision
The line is now annotated. Hover over it to see the decision.
Commands
| Command |
Description |
Decision Log: Add Decision |
Annotate the current selection with a new ADR |
Decision Log: View All Decisions |
Open a panel listing all decisions in the workspace |
Decision Log: Delete Decision |
Delete a decision (also available from hover tooltip) |
Configuration
| Setting |
Default |
Description |
decisionLog.storageFolder |
.decisions |
Folder (relative to workspace root) where decision JSON files are stored |
decisionLog.showGutterIcons |
true |
Show background highlight on annotated lines |
Decisions are stored as human-readable JSON in .decisions/. Each source file gets its own JSON file keyed by a hash of its path.
{
"filePath": "src/auth/TokenService.ts",
"decisions": [
{
"id": "uuid-here",
"startLine": 42,
"endLine": 55,
"title": "Use short-lived JWT tokens (15 min)",
"rationale": "Reduces exposure window if a token is leaked. Refresh tokens handle the UX cost.",
"author": "@alice",
"createdAt": "2026-01-15T10:30:00.000Z"
}
]
}
Tip: Add .decisions/ to your git repository so decisions are shared with your team.
Tips
- Team onboarding: New developers can read all decisions with
View All Decisions to understand the codebase's history
- PR reviews: Add a decision before you push so reviewers see your reasoning inline
- Refactoring: When you change code, update or delete outdated decisions to keep them accurate
Release Notes
0.1.1
- Fix: Extension no longer crashes on activation when no workspace folder is open (
ENOENT: no such file or directory, mkdir '.decisions'). The .decisions/ directory is now created lazily on first write instead of eagerly at startup.
0.1.0
