Decisions (ADRs)

Overview

The Decisions module is Vigilo's Architecture Decision Record (ADR) log — a workspace-scoped, append-mostly list of the choices your team has made and the reasoning behind them. It lives under /ws/{slug}/decisions and sits alongside Risks and Compliance in the Governance group of the main sidebar.

Each row captures a single decision: a title, the status it's currently in (proposed, accepted, rejected, superseded), the date it was decided, and a markdown body covering context, options considered, the chosen path, and the consequences.

Why it exists

Tribal knowledge is the single biggest tax on growing teams. Six months after a debate about "Kafka vs Redis Streams" or "REST vs gRPC for the internal API", three new engineers join and one of them re-opens the same argument because nobody wrote down what was decided and why. ADRs prevent the re-litigation. They also save auditors and security reviewers a week of guesswork: a clear paper trail of architectural intent is one of the cheapest controls you can implement.

Vigilo deliberately keeps decisions terse and structured rather than turning them into a wiki. The frontmatter (title + status + date) is the index; the body is the rationale. Decisions are sorted by decided_at descending so the freshest context is on top.

Key concepts

• Decision fields — title, status (proposed, accepted, rejected, superseded), decided_at (date, nullable while proposed), body (markdown), decided_by (UserProfile, the person who landed the call), supersedes (optional FK to a prior decision this one replaces).
• Status transitions — typical flow is proposed → accepted (or → rejected). Once a decision has been replaced by a newer one, set the old row to superseded and reference the new row via supersedes. The list view shows superseded rows greyed-out so the live answer is unambiguous.
• Search — the search box matches against title and status. The body is intentionally not indexed in the in-page search to keep results focused on the question; use Knowledge base search for full-text.
• Linking from elsewhere — paste a decision URL anywhere markdown is rendered (change body, runbook step, KB page) and Vigilo auto-resolves it to a chip showing the title and current status.

Common workflows

1. Record a new decision

1. Open Governance → Decisions → + New decision (the "+" icon in the header).
2. Title: a single sentence in present tense ("Use Postgres for the audit chain", not "We will use Postgres for the audit chain").
3. Body: cover four sections — Context, Options considered, Decision, Consequences. Markdown supported.
4. Set status to proposed while it's being reviewed. Set the date and flip to accepted once the team has signed off.
5. Save. The row appears at the top of the list with the new status badge.

2. Supersede an old decision

1. Open the new decision in edit mode.
2. Set the Supersedes field to the older row (the picker filters by status; you'll typically be replacing an accepted decision).
3. Save. Vigilo automatically flips the older decision's status to superseded and writes a cross-reference both ways.
4. Both rows remain visible — the older one shows a "superseded by" chip, the newer one shows the inverse. Auditors can walk the chain.

3. Browse the history quickly

1. The list view is sorted by decided_at descending. The freshest context is always on top.
2. Use the status filter chips to narrow to accepted (the live consensus) or superseded (the archaeology layer).
3. The empty state explains the model: "Capture architecture decisions as they happen so the reasoning isn't lost." A short prompt is better than a blank page.

4. Link a decision from a change

1. In the change body or comments, paste the decision URL (e.g. /ws/{slug}/decisions/<id>).
2. Vigilo auto-renders a chip: [ACCEPTED] Use Postgres for the audit chain.
3. The change detail's "Mentions" panel collects every linked decision so a reviewer can read the rationale without leaving the change.

Permissions

Decision endpoints inherit WorkspaceScopedMixin. Workspace A never sees Workspace B's decision log.

Troubleshooting

A decision shows the wrong status after I superseded it. The supersession is one-way. Setting supersedes on the new row auto-flips the old one to superseded; clearing it does not revert the old status. To undo, open the old decision and set the status back manually.

The list looks empty even though I just created one. Confirm you're in the right workspace. Decisions are workspace-scoped — switching workspaces with the picker in the top bar will swap the list.

I want to attach a diagram or screenshot. The body is markdown; paste a public URL or upload to a KB space and link from the decision. The decision rows do not own file attachments themselves to keep them lightweight.

Related articles

• Audit log — every decision edit writes an immutable audit row.
• Risk register — link a risk to the decision that mitigated it.
• Docs spaces — longer-form rationale documents that don't fit the ADR format.