Decision Management

Overview

Document and preserve all architectural decisions. Enables cross-orchestrator learning and prevents wheel reinventing.

ROI: Saves 30-60 min/session by reviewing past decisions first.

Why This Matters

Before (Old Way)

❌ Decisions buried in Slack messages, PR descriptions, meeting notes ❌ Every orchestrator reinvents the wheel ❌ No way to search "have we decided this before?" ❌ Conflicting decisions across teams ❌ Institutional knowledge lost when people leave

After (New Way)

✅ All decisions in markdown files under version control ✅ Review past decisions before deciding (prevents duplication) ✅ Cross-orchestrator learning via shared files ✅ Knowledge preserved and reusable ✅ Decision history tracked in git

How It Works

Decisions are stored as markdown files in docs/planning/decisions/. Each decision is a standalone file with a consistent structure. Use grep or your editor's search to find past decisions.

Creating a Decision Record

Decision File Location

docs/planning/decisions/YYYY-MM-DD-short-title.md

Examples:

docs/planning/decisions/2026-02-03-use-supabase-postgresql.md
docs/planning/decisions/2026-02-10-deploy-cron-to-mac-studio.md
docs/planning/decisions/2026-02-15-store-credentials-in-1password.md

Decision File Template

# Decision: [Title]

**Date:** YYYY-MM-DD
**Status:** Active | Superseded | Deprecated
**Impact:** critical | high | medium | low
**Category:** architecture | process | tooling | infrastructure | security
**Department:** fp | omg | lm | tech | legal | finance

## Decision

[One or two sentences describing the decision made.]

## Rationale

[Why was this decision made? What problem does it solve?]

## Alternatives Considered

- **[Option A]:** [Why it was rejected]
- **[Option B]:** [Why it was rejected]

## Consequences

[What are the downstream effects of this decision?]

## Supersedes

[Link to any previous decision this replaces, if applicable]

Searching for Past Decisions

Before implementing any solution, search existing decisions:

# Search by keyword
grep -r "keyword" docs/planning/decisions/

# Search by category
grep -rl "Category: architecture" docs/planning/decisions/

# Search by topic (case-insensitive)
grep -ril "database" docs/planning/decisions/
grep -ril "sync" docs/planning/decisions/
grep -ril "rate limit" docs/planning/decisions/

# List all decisions
ls docs/planning/decisions/

# List recent decisions
ls -lt docs/planning/decisions/ | head -20

The Mandatory Search-First Rule

ALWAYS Review Past Decisions Before Deciding

Rule: Search for related decisions BEFORE implementing any solution.

Why: Someone may have already solved this problem. Searching takes 30 seconds. Reimplementing takes 30-60 minutes.

# Example: About to implement a new API integration
grep -ril "api integration" docs/planning/decisions/
grep -ril "zendesk" docs/planning/decisions/

# Read the matching decision file
cat docs/planning/decisions/2026-02-03-api-integration-standard.md

Recording Decisions

When to Record

Record a decision whenever you:

Choose between 2+ alternatives
Set a technical standard
Select a tool or library
Define a process or workflow
Make an architectural choice
Establish a convention

Examples:

"Use sync profiles instead of custom API clients"
"Store credentials in 1Password"
"Use Supabase views for dashboard queries"
"Deploy cron jobs to Mac Studio"
"Send alerts to Slack #tech-alerts channel"

When NOT to Record

Don't record:

Implementation details (put in code comments)
Temporary workarounds (note in PR description)
Personal preferences (unless they become team standards)
Obvious choices with no alternatives

Decision Attributes

Impact Level

Level	Description	Examples
`critical`	Affects entire system, hard to change	Database choice, Auth system, Core architecture
`high`	Affects multiple components, effort to change	API integration, Data model, Deployment strategy
`medium`	Affects single component, moderate effort	Library choice, File structure, Naming convention
`low`	Easily changeable, minimal impact	Code style, Variable naming, Comment format

Category	Description	Examples
`architecture`	System design, data models	Database choice, API design, Service architecture
`process`	Workflows, procedures	Code review process, Deployment workflow
`tooling`	Tools, libraries, services	Library selection, Tool adoption
`infrastructure`	Hosting, services, operations	Cron jobs, Monitoring, Backups
`security`	Authentication, authorization	Credential storage, API keys

Department

Department	Description
`fp`	FLYPILOT organization-wide
`omg`	OMG Interactive specific
`lm`	Learned Media specific
`tech`	Technology department
`legal`	Legal department
`finance`	Finance department

Real-World Examples

Example 1: Infrastructure Choice

# Decision: Deploy cron jobs to Mac Studio

**Date:** 2026-02-03
**Status:** Active
**Impact:** high
**Category:** infrastructure
**Department:** fp

## Decision

All automated cron jobs are deployed to the Mac Studio.

## Rationale

Always-on machine with Tailscale VPN. Can access Supabase and external APIs
without additional networking configuration.

## Alternatives Considered

- **Vercel cron:** Limited free tier, harder to debug
- **AWS Lambda:** More complex setup, cost at scale

## Tags

cron, mac-studio, deployment

Example 2: Tool Selection

# Decision: Use sync profiles instead of custom API clients

**Date:** 2026-02-03
**Status:** Active
**Impact:** high
**Category:** process
**Department:** fp

## Decision

All external data access goes through sync profiles in `flypilot/sync/`.
No custom API client code should be written by orchestrators.

## Rationale

The sync system is tested, rate-limited, and production-ready. Writing
custom clients duplicates code and introduces error-prone API handling.

## Alternatives Considered

- **Custom clients per orchestrator:** Leads to duplicated code and rate limit errors

Example 3: Security Decision

# Decision: Store all credentials in 1Password

**Date:** 2026-02-03
**Status:** Active
**Impact:** critical
**Category:** security
**Department:** fp

## Decision

All credentials are stored in 1Password and accessed via `op read`.

## Rationale

Centralized secret management with audit trail and CLI access for automation.

## Alternatives Considered

- **Environment variables:** Hard to rotate across machines
- **.env files:** Risk of accidental commits
- **AWS Secrets Manager:** Overkill for current scale

Superseding Decisions

When circumstances change, mark the old decision as superseded and create a new one.

In the old decision file:

**Status:** Superseded

> **Superseded by:** [2026-03-01-use-supabase-postgresql.md](./2026-03-01-use-supabase-postgresql.md)
> **Date superseded:** 2026-03-01

In the new decision file:

## Supersedes

[2026-02-03-use-local-postgresql.md](./2026-02-03-use-local-postgresql.md) — switching
to managed Supabase PostgreSQL for built-in auth and REST API.

Why keep old decisions?

Shows why we changed direction
Prevents revisiting already-rejected alternatives
Provides historical context for newcomers

Integration with Workflow

Before Every Session

# Search for related past decisions
grep -ril "topic of work" docs/planning/decisions/
ls docs/planning/decisions/ | grep "keyword"

During Work

# When you make a significant choice, create a decision file
cp docs/planning/decisions/_template.md \
   docs/planning/decisions/$(date +%Y-%m-%d)-short-title.md

# Fill in the template and commit it

End of Session

# Verify you documented decisions
ls -lt docs/planning/decisions/ | head -5
git diff --name-only | grep decisions/

Best Practices

Search before deciding - Always. Use grep across the decisions directory.
Record immediately - Don't wait until end of day; details fade fast.
Be specific - "Use PostgreSQL" is better than "Choose database"
Explain why - Rationale is the most important field.
List alternatives - Shows you considered options.
Supersede, don't delete - Shows decision evolution.
Commit decisions with the code change - Keep them together in git history.

Success Metrics

After 1 week:

✅ 10+ decisions recorded as files
✅ Decisions being referenced across sessions
✅ Zero conflicting approaches discovered

After 1 month:

✅ 30+ decisions (knowledge base growing)
✅ New sessions reference existing decisions
✅ Reduced duplicate work

Why This Matters​

Before (Old Way)​

After (New Way)​

How It Works​

Creating a Decision Record​

Decision File Location​

Decision File Template​

Searching for Past Decisions​

The Mandatory Search-First Rule​

Recording Decisions​

When to Record​

When NOT to Record​

Decision Attributes​

Impact Level​

Category​

Department​

Real-World Examples​

Example 1: Infrastructure Choice​

Example 2: Tool Selection​

Example 3: Security Decision​

Superseding Decisions​

Integration with Workflow​

Before Every Session​

During Work​

End of Session​

Best Practices​

Success Metrics​

Related Documentation​