Investiture Skill: Decision Record
You are capturing a decision before it becomes invisible. Architecture decisions made without records cause confusion months later when no one remembers why a choice was made — or worse, when the same decision gets relitigated. This skill takes a decision in flight and turns it into a permanent, numbered, cross-referenced ADR.
This skill runs on demand. It does not depend on invest-doctrine or invest-architecture having run first, but it reads doctrine files to inform the ADR. It writes to /vector/decisions/, which invest-backfill initializes. If doctrine files are missing, the skill flags what context is absent and continues.
Step 0: Get the Decision Description
If a decision description was passed as an argument, use it directly.
If no argument was provided, prompt the operator:
What decision are you capturing? Describe it as a question or a choice: Examples: "Should we add Supabase or stay local-first with IndexedDB?" "Use React Query vs. manual fetch + useEffect for data loading" "Deploy as Cloudflare Worker vs. Netlify serverless function"
Step 1: Read Doctrine
Read the following files. They define the constraints and context within which this decision lives.
VECTOR.md— Extract: constraints (hard limits), value proposition (what this product must do), design principles (philosophy that should guide decisions), project stage.ARCHITECTURE.md— Extract: current stack (what is already in use), declared preferences, existing patterns, "What Not to Do" prohibitions./vector/decisions/— List all existing ADR files. Read their titles and decisions. You need this to:- Number the new ADR correctly (next in sequence after the highest existing number)
- Identify prior decisions this new one must not contradict
- Find prior decisions this one supersedes or relates to
If VECTOR.md or ARCHITECTURE.md is missing, flag it and continue — you can still write a useful ADR, but note which context is missing.
If /vector/decisions/ does not exist, create it. The new ADR will be the first: ADR-001.
Step 2: Determine the ADR Number and Slug
Numbering: Find the highest existing ADR number in /vector/decisions/. The new ADR is that number + 1, zero-padded to three digits: 001, 002, 031, 100.
If no ADRs exist, start at ADR-001.
Slug: Derive from the decision description. Lowercase, hyphenated, 3-6 words:
- "Should we add Supabase or stay local-first with IndexedDB?" →
supabase-vs-indexeddb - "Use React Query vs. manual fetch" →
react-query-vs-manual-fetch - "Deploy as Cloudflare Worker vs. Netlify" →
cloudflare-worker-vs-netlify
Filename: ADR-[NNN]-[slug].md
Step 3: Analyze the Decision
Before writing the ADR, think through the decision using the doctrine context:
Options identification: What are the real alternatives? There are almost always at least two, sometimes three. Name them clearly. "Do nothing / keep the current approach" is always a valid option and often worth including.
Constraint filtering: Which options are ruled out by VECTOR.md constraints or ARCHITECTURE.md prohibitions? For example, if VECTOR.md says "no external dependencies," cloud-hosted databases are eliminated. State this explicitly — eliminating options based on declared constraints is faster than evaluating them.
Stack compatibility: Which options fit the existing stack without friction? Which require new dependencies, new patterns, or new expertise?
Value prop alignment: Does one option better serve the core value proposition in VECTOR.md? If yes, that's a meaningful signal, not just a technical preference.
Prior ADR cross-reference: Does any existing ADR constrain this decision? For example, a prior ADR establishing "local-first architecture" would weigh heavily against a cloud-hosted option. If a prior ADR is directly relevant, reference it by number.
Step 4: Draft the ADR
Write a complete ADR using this structure:
markdown# ADR-[NNN]: [Decision Title — present tense, descriptive] **Date:** [today's date] **Status:** [proposed | accepted | deprecated | superseded by ADR-NNN] **Deciders:** [OPERATOR: List who was involved in this decision, or remove this line] ## Context [2-4 sentences. What is the situation that requires a decision? What problem are we solving? What constraints apply from VECTOR.md or ARCHITECTURE.md? What is the cost of not deciding?] ## Decision Drivers [Bullet list of the factors that matter most for this decision. These come from VECTOR.md constraints, ARCHITECTURE.md preferences, and project stage. Be specific — not "performance" but "must render under 100ms on low-end devices."] - [Driver 1 — sourced from doctrine if possible] - [Driver 2] - [Driver 3] ## Options Considered ### Option A: [Name] [1-2 sentences describing this option.] **Pros:** - [Concrete advantage — specific to this project, not generic] - [Another advantage] **Cons:** - [Concrete disadvantage or risk] - [Another disadvantage] ### Option B: [Name] [Same structure] ### Option C: [Name, if applicable] [Same structure] ## Decision **We will [chosen option].** [2-3 sentences explaining why this option was chosen. Reference the decision drivers that it best satisfies. If a constraint from VECTOR.md or a prior ADR was the deciding factor, say so explicitly.] ## Consequences **Positive:** - [What gets better or easier] - [What new capability this enables] **Negative:** - [What this forecloses — options that are now off the table] - [Technical debt or tradeoffs this introduces] - [What will need to be revisited if circumstances change] **Neutral:** - [Side effects that aren't good or bad, just worth knowing] ## Related Decisions [List any ADRs that this decision relates to, supersedes, or is constrained by. Format: `ADR-NNN: [Title]`. Or "None." if this is the first ADR.]
On the [OPERATOR: ...] bracket in Deciders: Leave it exactly as written. Do not guess or fill in who was involved — that's for the operator to provide. If you do not know who made the decision, leave the bracket.
Status field:
proposed— Decision is being considered, not yet finalized. Default if no--statusflag was passed.accepted— Decision is final.deprecated— The decision is no longer in effect but wasn't superseded by a specific newer ADR.superseded by ADR-NNN— A newer decision replaced this one.
If --status was passed as an argument, use that value.
Step 5: Present for Confirmation
Output the drafted ADR to the terminal in full. Then ask:
ADR-[NNN]-[slug].md drafted above. Write to /vector/decisions/ADR-[NNN]-[slug].md? (yes/no)
If --dry-run was passed: Output the ADR to the terminal and stop. Do not write the file, do not ask for confirmation.
Step 6: Write the File
On confirmation, write to /vector/decisions/ADR-[NNN]-[slug].md.
Create /vector/decisions/ if it does not exist.
Output the final ADR to the terminal and save it to /vector/decisions/ADR-[NNN]-[slug].md. Each ADR is a new sequential file — do not overwrite existing ADRs.
After writing, output:
ADR-[NNN] written to /vector/decisions/ADR-[NNN]-[slug].md [If this supersedes a prior ADR:] Note: You may want to update ADR-[prior NNN] to set its status to "superseded by ADR-[NNN]."
Arguments
- No arguments: Interactive — prompts for decision description, uses
--status proposedby default [decision description]: Uses the argument as the decision description, skips the prompt--status [proposed|accepted|deprecated|superseded]: Sets the ADR status field--dry-run: Drafts and displays the ADR without writing the file
Output
/vector/decisions/ADR-[NNN]-[slug].md
When to Run
- Before committing to a new dependency or external service
- Before adopting a new architectural pattern that will propagate across the codebase
- Before making a choice that is hard to reverse
- When the same decision keeps coming up — record it so it stops being relitigated
- After a significant pivot — record what changed and why
Principles
- One decision, one ADR. Don't bundle multiple choices into a single record. If you're deciding both the state management library AND the data fetching strategy, write two ADRs.
- Constraints are filters, not opinions. If VECTOR.md rules something out, say so clearly. You're not making a judgment call — you're applying declared doctrine.
- "Do nothing" is always an option. Including the status quo as an evaluated option makes the decision more honest.
- Specificity over generality. "Fast enough for our users" is not a decision driver. "Must render initial content under 200ms on a 3G connection" is.
- Consequences matter as much as the decision. The point of an ADR is not just to record the choice — it's to record what it forecloses. Future contributors need to know what they're inheriting.
