Engineering Request for Comments (RFC)

Template Overview

Writing code before establishing architectural consensus is the most expensive mistake an engineering team can make. Engineers spend three weeks building a feature, only to have their pull request rejected during code review because of unconsidered security boundaries, database locking issues, or API contract collisions.

An engineering Request for Comments (RFC) shifts technical collaboration upstream. Before committing code, the author articulates the proposed design, details data models and API schemas, analyzes failure modes, and solicits rigorous critique from staff engineers.

This template provides an engineering-grade RFC format: proposal summary, detailed technical design, database schemas, security and privacy threat modeling, migration rollouts, and open unresolved questions.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "RFC: [Proposed System Architecture / Feature]"
date: [YYYY-MM-DD]
rfc_number: 52
author: "[[Staff Systems Engineer]]"
sponsors:
  - "[[Chief Architect]]"
  - "[[VP Engineering]]"
target_implementation_sprint: "Sprint 26"
rfc_status: [Draft / Open for Comments | Under Review | Approved | Withdrawn]
feedback_deadline: 2026-10-25
tags: [rfc, engineering, architecture, proposal, systems]
---

# RFC: [Proposed System Architecture / Feature] — [YYYY-MM-DD]

## 1. Executive Summary & Problem Motivation
- **Proposal Summary:** Implement an on-device semantic vector embedding search engine for personal Markdown vaults, executing purely on the Apple Silicon Neural Engine (ANE) with zero external network transmission.
- **Problem Motivation:** Full-text keyword search (FTS5) requires exact term matching and fails when users query concepts (e.g. querying 'financial runway' fails to match notes containing only 'burn rate and cash reserves').

## 2. Detailed Technical Architecture & Pipeline
### Ingestion & Chunking Pipeline
1. File watcher detects new or mutated `.md` files in user vault.
2. Ingestion pipeline strips frontmatter and chunks document into 512-token overlapping windows.
3. Quantized embedding model (`bge-small-en-v1.5` CoreML export) generates 384-dimensional dense vectors on the Neural Engine.
4. Vectors are persisted into an embedded vector index using Apple Accelerate framework for SIMD vector distance calculations.

### System Topology Diagram
```text
[ Markdown Vault File ]
          │
          ▼
[ File Mutation Watcher ] ──► [ Tokenizer & Chunking ]
                                       │
                                       ▼
                             [ Apple Neural Engine ]
                             (CoreML Embedding Model)
                                       │
                                       ▼
                             [ Accelerate Vector Index ] ◄──► [ Local UI Search ]

3. Data Schema & Persistence Model

CREATE TABLE IF NOT EXISTS vault_embeddings (
    chunk_id TEXT PRIMARY KEY,
    note_path TEXT NOT NULL,
    chunk_index INTEGER NOT NULL,
    chunk_text TEXT NOT NULL,
    embedding BLOB NOT NULL, -- 384 x float32 (1536 bytes)
    updated_at INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_note_path ON vault_embeddings(note_path);

4. Security, Privacy & Threat Modeling

• Zero Network Transmission: The CoreML model executes strictly in local unified RAM. Zero telemetry or inference tokens are transmitted to cloud endpoints.
• App Sandbox Compliance: Temporary vector memory allocations are contained within the macOS application container directory.

5. Rollout Strategy, Migration & Rollback Plan

• Phase 1 (Canary): Release behind feature flag (FEATURES.semanticSearch = false) to internal engineering dogfooders.
• Phase 2 (Beta): Enable opt-in toggle in Settings -> Advanced Lab for beta cohort.
• Rollback Procedure: If RAM usage exceeds 150MB RSS on 8GB Macs, feature flag will disable vector indexing and fall back to SQLite FTS5.

6. Unresolved Open Questions for Reviewers

1. Should embedding generation pause automatically when the Mac transitions to battery power?
2. What is the maximum acceptable vault size before initial index generation time exceeds 10 minutes?

• Review feedback from [[Lead Security Engineer]].
• Schedule 30-minute ARB review before [[YYYY-MM-DD]].

## Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

```markdown
---
title: "RFC-0052: On-Device Vector Search"
date: 2026-10-06
rfc_number: 52
author: "[[Alex Rivera]]"
rfc_status: Open for Comments
tags: [rfc, engineering]
---

# RFC-0052: On-Device Vector Search — October 6, 2026

## 1. Summary
Proposes on-device semantic vector search using CoreML on Apple Neural Engine. Zero external network egress.

## 2. Status
Open for review. Feedback deadline October 25, 2026.

When to Use and When to Avoid

When to Use

• Use prior to implementing major engineering systems, schema migrations, or infrastructure overhauls.
• Use to solicit cross-team peer review and build technical consensus before writing code.
• Use to document security boundaries, failure modes, and rollout plans.

When to Avoid

• Avoid using for minor bug fixes, copy changes, or routine dependency updates.
• Avoid using as a post-implementation record (use [[architecture-decision-record]]).

On-Device AI Integration

Capture engineering RFC debates with Oyma on macOS:

Analyze the engineering RFC review meeting transcript:
1. Synthesize the proposal motivation, core architectural changes, and underlying technical pipeline.
2. Outline the data schemas, concurrency models, and system topology proposed.
3. Detail security threat modeling considerations and sandbox compliance verifications.
4. Record reviewer feedback, consensus decisions, rollout plans, and unresolved open questions.
Output in rigorous, engineering-grade CommonMark.

Your unreleased engineering proposals and architectural RFCs stay strictly private on your Mac.