Create Your First Decisions

Don't try to document everything at once. Start with 3-5 decisions that are actively shaping your architecture:

• A recent decision that's fresh in everyone's mind
• A foundational decision that everything depends on
• An upcoming decision that needs discussion

The fastest way to create decisions. Paste raw text from Slack, email, or meeting notes, and let AI extract the structure.

1. Click New Decision in the navigation
2. Select Magic Paste
3. Paste unstructured text like:
   "After yesterday's meeting, we agreed to use PostgreSQL instead
   of MySQL for the new service. Main reasons were the JSON support
   and better performance under our read-heavy workload."
4. Click Extract
5. Review and edit the extracted decision, then save

For new decisions that don't exist yet, use Spark to scaffold a well-structured record through conversation.

1. Click New Decision → Spark
2. Describe what you're deciding:
   "We need to decide between Kafka and RabbitMQ for our event
   streaming. Main concerns are throughput and operational complexity."
3. Spark will ask clarifying questions and generate a draft
4. Review, edit, and publish

When you're viewing the graph and want to add a decision quickly:

1. Navigate to the Graph view
2. Double-click anywhere on the canvas
3. Enter a title and optional context
4. The decision appears right where you clicked

This is great for sketching out related decisions quickly.

Arguments capture the reasoning behind positions. Each argument has:

• Claim: The point being made ("PostgreSQL has better JSON support")
• Position: Whether it supports or opposes a position
• Evidence: Optional links to back up the claim

To add an argument:

1. Open a decision
2. Scroll to a position and click Add Argument
3. Write your claim and add optional evidence

Relationships are what make Arbtr powerful. They turn isolated decisions into a connected graph.

To create a relationship:

1. Open a decision or view the graph
2. Click Add Relationship
3. Select the type:
   • depends_on: This requires that to work
   • enables: This makes that possible
   • conflicts: These can't coexist
   • supersedes: This replaces that
4. Select the target decision

Here's an example of what your first graph might look like:

  ┌─────────────────────────┐
  │   Use PostgreSQL for    │
  │      user data          │◄──────────┐
  └───────────┬─────────────┘           │
              │ enables                 │ depends_on
              ▼                         │
  ┌─────────────────────────┐           │
  │   Implement JSONB for   ├───────────┘
  │   flexible metadata     │
  └───────────┬─────────────┘
              │ enables
              ▼
  ┌─────────────────────────┐
  │   Build user preference │
  │      system             │
  └─────────────────────────┘
              

Three connected decisions showing how database choice enables features further down the stack.

You've got the basics. Next steps:

• Connect your Git provider
• Explore Strategic Branches for what-if scenarios
• Let Arbiter analyze your graph for insights