User Guide

1. Create an account

Sign up with your GitHub account or an email and password at /signup. GitHub OAuth is the fastest path — one click and you land in the onboarding flow.

2. Create a workspace

A workspace is a shared space for one team or project. On first login you are prompted to create one. Give it a name (e.g. "Platform team" or "Acme backend") and you land in your dashboard.

3. Log your first decision

Click New decision (or press c on the dashboard) and fill in:

• Title — a short, searchable label
• Problem — what question you are trying to answer
• Options — the alternatives you considered
• Decision — what you chose and why
• Tradeoffs — what you accepted, mitigated, or deferred

All fields except Title are optional, but a complete decision is far more useful six months later.

Status lifecycle

Every decision moves through three states:

• Proposed — under discussion; open for comments and approvals.
• Accepted — finalized; unblocks any linked GitHub PR.
• Superseded — replaced by a newer decision; kept for historical context.

Lifecycle timeline

Every decision detail page shows a three-step visual timeline — Proposed → Approved → Accepted/Superseded — with the date and actor for each step. The Approved step lists every team member who clicked Approve, so you always have an audit trail of who signed off and when.

Review date & reviewer

Set a Review date to schedule when the decision should be revisited. Assign a Reviewer to make accountability explicit. The reviewer receives an in-app notification and an email when assigned. Decisions past their review date appear as overdue in the nav badge.

Version history

Every time you save a decision, a snapshot is stored. The last 20 versions are listed at the bottom of the detail page with the editor's name and timestamp. Useful for understanding how a decision evolved over time.

Duplicate a decision

Click Duplicate on any decision to create a copy pre-set to Proposed. Handy for recurring decisions that share the same structure (e.g. quarterly vendor reviews).

When creating a new decision, choose a template to skip the blank-page problem. Templates pre-fill the Problem, Options, Decision, and Tradeoffs fields with a scaffold you can edit.

The Problem, Options, Decision, and Tradeoffs fields support Markdown. On the decision detail page, a collapsible Preview (rendered) panel above the edit form shows the content formatted — headings, bold, italic, bullet lists, and code blocks are all rendered.

Tags let you group related decisions across your workspace. Add a tag by typing in the tag field on the decision detail page and clicking Add. Tags are shared across the workspace — typing an existing tag name reuses it.

Filter decisions by tag on the dashboard using the tag pills. Combine with status filters and search for precise queries (e.g. all Proposed decisions tagged infrastructure).

Link decisions together to capture how they depend on or replace each other. Three relation types are supported:

• Supersedes — this decision replaces an older one. The older decision should usually be set to Superseded.
• Depends on — this decision only makes sense in the context of another. If the depended-on decision changes, this one should be reviewed.
• Related to — a loose association; useful for grouping decisions from the same project or spike.

Links appear on both decisions (as outgoing and incoming), so you can navigate the graph from either end.

Search

The search bar runs a full-text query across the Title, Problem, and Decision fields of every decision in the current workspace. Results update as you type.

Filters & sorting

• View — All decisions or My reviews (decisions you are assigned to review).
• Status — All / Proposed / Accepted / Superseded.
• Tags — One tag at a time; combine with status and search.
• Reviewer — Filter by any workspace member.
• Sort — Newest, Oldest, Title (A–Z), Review date (soonest first).

My reviews

Click My reviews in the View row to instantly scope the list to decisions where you are the assigned reviewer. Useful as a daily starting point for reviewers.

Keyboard shortcut

Press c anywhere on the dashboard (when no input field is focused) to jump directly to the new decision form. A hint is shown at the bottom of the decision list as a reminder.

Overdue badge

The Dashboard link in the nav shows a red count badge when you have one or more decisions past their review date where you are the reviewer and the status is still Proposed. Click the badge to go to the dashboard, then use My reviews to see them.

Approvals

Any workspace member (except the decision's proposer) can click Approve decision on the detail page. Approvals are permanent and time-stamped. The lifecycle timeline shows every approver with their name and the date they approved.

Comments

Add comments to discuss the decision. Comments are visible to all workspace members and are ordered chronologically. Write in Markdown — the comment field supports the same syntax as the decision fields.

Inviting team members

From the dashboard header, click Invite to generate a link scoped to your workspace. Send it to anyone — they sign up (or log in) and land directly in your workspace. Each invite link can be used once.

Roles

Two roles exist per workspace:

• Owner — can change member roles, remove members, connect GitHub, and delete the workspace.
• Member — can create and edit decisions, comment, and approve.

Owners can promote members or demote themselves in the workspace Settings page.

Read-only share link

On any decision detail page, click Generate share link to create a public, token-based URL. Anyone with the link can read the decision without logging in — useful for sharing with stakeholders. Click Revoke link to instantly invalidate it.

Export a single decision

Click Export .md on the decision detail page to download that decision as a Markdown file. The format follows the standard ADR (Architecture Decision Record) convention and is compatible with most ADR tools.

Export all decisions

From the dashboard header, click Export all to download every decision in the current workspace as a single Markdown archive. Useful for backups or migrating to another tool.

Print / PDF

Click Print on the decision detail page to open the browser print dialog. The page uses a print stylesheet that hides the navigation and action buttons, leaving a clean one-page layout suitable for PDF export.

Setup: four steps

1. 1Connect GitHub — from the dashboard header, click Connect GitHub and install the GitHub App on the organizations or repos you want to monitor. Each workspace connects to one installation.
2. 2Open a PR — when a pull request is opened or updated that touches architectural files, the app posts a comment asking the author to log a decision, and adds a decision-log/approval status check set to pending. The author can click the check's Details link to open Decision Log with the PR context pre-filled.
3. 3Create and approve a decision — fill in the problem, options, and decision. Once marked Accepted, the decision-log/approval check updates to success automatically.
4. 4Require the check (optional) — to block merge until a decision is approved, add a GitHub branch protection rule requiring decision-log/approval to pass before merging.

Which files trigger the check?

A PR is considered architectural if it changes a file whose path matches the configured patterns (case-insensitive). Default patterns:

Custom trigger rules

Add a decision-log-rules.json file to your repository root to override the defaults:

{
  "patterns": [
    "infra/",
    "docker/",
    ".github/workflows/",
    "schema.sql",
    "terraform"
  ]
}

Common questions

A workspace groups a team's decisions together. You can belong to multiple workspaces (e.g. one per product team) and switch between them using the workspace switcher in the dashboard header.

Create a workspace

Click New workspace in the dashboard header. Give it a name and you are set as the owner. Invite team members using the Invite flow.

Workspace settings

Click Settings in the dashboard header to:

• Rename the workspace
• Change member roles or remove members
• Connect or disconnect the GitHub App
• Delete the workspace (owners only)

Free plan limit

Each workspace on the free plan can hold up to 100 decisions. When the limit is reached, a banner appears on the dashboard and the New decision button is disabled. Create a new workspace or upgrade to continue.

In-app bell

The bell icon in the header shows a badge when you have unread notifications. Click it to see the list. Opening the panel marks all notifications as read. Notifications are generated when:

• You are assigned as reviewer on a decision
• A decision you are reviewing is approaching its review date

Email reminders

When a decision's review date is approaching, the assigned reviewer receives an email reminder. Reminders are sent by the scheduled reminder job — no action needed on your part.

Account settings

Click your email in the nav (or go to /account) to update your email address or change your password.

API keys

Generate personal API keys from Account → API keys. Each key grants programmatic access scoped to your account. Use them to integrate Decision Log with your own scripts or CI pipelines. Revoke any key at any time — revocation is immediate.