Tutorial 3 of 743% complete

6 minIntermediate

Decision Logging

Best practices for logging decisions

Decision Logging Best Practices

Duration: 6 minutes | Difficulty: Beginner-Intermediate

What Makes a Good Decision?

Based on logging 800+ decisions while building Continuity, here's what works:

The Perfect Decision Format

output

Question: Why did we [choose/implement/change] [X]?
Answer: Because [specific reason]. We rejected [alternative] due to [trade-off].
Tags: [category], [technology], [area]

Examples from Real Usage

Good Decision:

output

Question: Why use Redis for session caching?
Answer: Redis is ideal because: 1) In-memory for sub-ms reads,
2) Built-in TTL for auto-expiration, 3) Scales with Redis Cluster.
We rejected Memcached due to lack of persistence options.
Tags: caching, redis, sessions, infrastructure

Weak Decision:

output

Question: Why Redis?
Answer: It's fast.
Tags: database

The good decision is searchable, explains trade-offs, and future-you will understand it.

The 5 Decision Types

1. Technology Choices

When you pick a tool, library, or framework

output

Question: Why TypeScript over JavaScript?
Answer: Type safety catches bugs at compile time. IDE autocomplete
improves productivity. Refactoring confidence for large codebase.
Tags: language, tooling, typescript

2. Architecture Decisions

How you structure the system

output

Question: Why monorepo structure for Continuity?
Answer: Shared core library used by extension, CLI, and MCP server.
Single source of truth for types. Easy refactoring across packages.
Tags: architecture, monorepo, packaging

3. Implementation Choices

How you solved a specific problem

output

Question: Why bundle @continuity/core into MCP with esbuild?
Answer: Monorepo symlink was excluded by .vscodeignore, breaking
MCP at runtime. Bundling into single 373KB file eliminates symlink issues.
Tags: mcp, bundling, packaging, fix

4. Configuration Decisions

Why settings are set a certain way

output

Question: Why default autoDetectRelationships to false?
Answer: Auto-generated relationships were noisy at low thresholds.
Users must opt-in. Reduces clutter while allowing power users to enable.
Tags: configuration, relationships, noise-reduction

5. Rejection Decisions

Why you chose NOT to do something

output

Question: Why not use MongoDB for user data?
Answer: Eventual consistency issues with financial data. PostgreSQL's
ACID transactions required for payment processing reliability.
Tags: database, rejected, mongodb, postgresql

When to Log Decisions

Always Log:

•Choosing between technologies
•Adding significant dependencies
•Changing core architecture
•Fixing bugs that might recur
•Configuration with non-obvious reasoning

Skip Logging:

•Trivial code formatting choices
•Standard library usage
•Temporary debugging decisions
•Personal preferences with no team impact

Tagging Strategy

Use Consistent Tag Categories

Category	Example Tags
Technology	`postgresql`, `redis`, `typescript`, `react`
Area	`authentication`, `api`, `frontend`, `testing`
Type	`architecture`, `bug-fix`, `configuration`, `security`
Status	`rejected`, `deprecated`, `experimental`

Tag Naming Conventions

•Lowercase: database not Database
•Hyphenated: bug-fix not bugfix or bug_fix
•Specific: postgresql not just database
•2-5 tags per decision: Too few = unsearchable, too many = noise

The Question Formula

Your question should be answerable by someone who wasn't there:

Pattern: "Why did we [verb] [noun]?"

Good questions:

•"Why did we choose PostgreSQL over MongoDB?"
•"Why did we implement rate limiting at the API gateway?"
•"Why did we reject WebSockets for notifications?"

Weak questions:

•"Database?" (not a question)
•"Why PostgreSQL?" (missing context)
•"What about caching?" (too vague)

The Answer Formula

Structure: Reason + Trade-off + Alternative

output

Answer: [Primary reason for the choice].
        [What we considered].
        [Why alternatives were rejected].

Example:

output

Answer: MiniLM embeddings enable semantic search without external APIs.
        Considered OpenAI embeddings but require API key and cost money.
        Local computation means zero privacy concerns and no latency.

Avoiding Common Mistakes

Mistake 1: Too Vague

output

❌ Answer: "It's better"
✅ Answer: "PostgreSQL's JSONB support enables flexible schemas while
   maintaining ACID transactions, unlike MongoDB's eventual consistency"

Mistake 2: No Trade-offs

output

❌ Answer: "We used React"
✅ Answer: "React for component model and ecosystem. Vue considered but
   team has more React experience. Svelte too new for enterprise."

Mistake 3: Duplicate Decisions

output

❌ Logging "Why PostgreSQL?" five times with slight variations
✅ One comprehensive decision, updated if reasoning evolves

Mistake 4: Wrong Granularity

output

❌ Logging every function name choice
✅ Logging the naming convention decision once

Decision Relationships

When decisions relate to each other, link them:

output

@continuity log_decision
question="Why add Redis caching layer?"
answer="Database queries taking 200ms+ under load. Redis provides <1ms reads."
tags=["caching", "redis", "performance"]

If this supersedes a previous decision:

output

@continuity update_decision
id="decision-45"
status="superseded"
reason="Replaced in-memory cache with Redis in decision-89"

Relationship Types

Type	When to Use
`supersedes`	New decision replaces old one
`relates_to`	Decisions are connected but independent
`conflicts_with`	Decisions cannot both be true
`depends_on`	Decision requires another to work

Using Templates

Continuity includes 19 templates. Use them:

output

Cmd+Shift+P → "Continuity: Log Decision"
→ Select template: "Technology Choice"

Templates provide structure for common decisions:

•Technology Choice
•Architecture Decision
•Bug Fix
•Configuration Change
•Security Decision
•Performance Optimization
•And 13 more...

Decision Lifecycle

Decisions aren't permanent. Update them:

Status Values

Status	Meaning
`active`	Current, in use
`deprecated`	Still works, but discouraged
`outdated`	No longer accurate
`superseded`	Replaced by newer decision

Priority Values

Priority	When to Use
`critical`	Core architecture, security
`high`	Important features, major dependencies
`medium`	Standard decisions (default)
`low`	Minor choices, experiments

Real Examples from Building Continuity

Example 1: Bug Fix Decision

output

Question: Why fix cosine similarity normalization in semantic search?
Answer: Scores were uniform 60% due to incorrect [-1,1] to [0,1]
normalization. MiniLM already produces [0,1] values. Fixed by using
raw similarity clamped to [0,1]. Now 80% for exact, 45-56% for related.
Tags: semantic-search, bug-fix, minilm, cosine-similarity
Priority: high

Example 2: Architecture Decision

output

Question: What is the complete Fluent AI Memory implementation?
Answer: 5-phase plan: 1) Auto-generate instruction files, 2) MCP ListTools
preamble, 3) FirstCallInjector context banner, 4) MessageInjector pattern
reminders, 5) MANDATORY FIRST ACTION section. Implementation time: 4 hours
vs estimated 12-16 hours.
Tags: architecture, fluent-memory, mcp, implementation-complete
Priority: critical

Example 3: Configuration Decision

output

Question: Why raise RelationshipDetector minConfidence from 30 to 50?
Answer: Auto-generated relationships were noisy. Combined with
autoDetectRelationships=false default, significantly reduces noise
while allowing power users to enable.
Tags: relationships, noise-reduction, thresholds
Priority: medium

Quick Reference Card

┌─────────────────────────────────────────────────────────────┐
│                 DECISION LOGGING CHECKLIST                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ☐ Question: "Why did we [verb] [noun]?"                    │
│  ☐ Answer: Reason + Trade-off + Alternative                 │
│  ☐ Tags: 2-5 tags, lowercase, hyphenated                    │
│  ☐ Priority: critical/high/medium/low                       │
│  ☐ Files: Link to relevant code files                       │
│  ☐ Relationships: Link to related decisions                 │
│                                                              │
│  Good Decision Test:                                         │
│  - Can someone new understand this in 6 months?              │
│  - Does it explain WHY, not just WHAT?                       │
│  - Are trade-offs documented?                                │
│  - Is it searchable by relevant keywords?                    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Key Takeaways

•Question = "Why did we [verb] [noun]?"
•Answer = Reason + Trade-off + Alternative
•Tags = 2-5, specific, lowercase, hyphenated
•Log technology choices, architecture, implementations
•Skip trivial formatting, standard library usage
•Update decisions when they become outdated

← Fluent AI Memory | Semantic Search →