Technical Spike Findings & Architecture Debrief

Template Overview

When software engineering teams encounter high architectural uncertainty—such as adopting a new database engine, testing an unfamiliar low-level OS API, or evaluating third-party algorithms—committing user stories immediately into a sprint backlog is a recipe for missed deadlines and throwaway code.

An engineering Technical Spike time-boxes exploratory prototyping to answer specific questions: Does this library meet our latency SLA? Can it run inside the macOS App Sandbox? What is the memory footprint under load?

This template captures spike outcomes: the framing question, prototyping methodologies, benchmark measurements, unexpected technical discoveries, and the concrete recommendation for production architecture.

Markdown Template Structure

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

---
title: "Technical Spike Debrief: [Spike Topic / System]"
date: [YYYY-MM-DD]
spike_lead: "[[Systems Engineer Name]]"
time_box_duration: "3 Days (24 Engineering Hours)"
prototype_repository: "github.com/org/spikes/audio-tap-poc"
recommended_path: [Adopt Architecture | Discard Prototype | Needs Further Research]
tags: [spike, prototype, benchmark, engineering, research]
---

# Technical Spike Debrief: [Spike Topic / System] — [YYYY-MM-DD]

## 1. Framing Hypothesis & Core Uncertainty
- **Spike Objective:** Determine whether macOS ScreenCaptureKit audio taps can capture system and microphone audio concurrently with zero dropped frames on baseline 8GB Apple Silicon hardware.
- **Core Uncertainty:** Does ScreenCaptureKit introduce higher CPU utilization or audio latency compared to legacy CoreAudio aggregate device kernel taps?

## 2. Experimental Methodology & Prototype Topology
- Built a standalone Swift command-line prototype (`sc-audio-test`) tapping active audio output streams.
- Subjected the test harness to 4 hours of continuous recording while simultaneously running simulated CPU stress tests (Xcode compilation loops).

## 3. Benchmark Measurements & Empirical Results
| Performance Metric | Legacy CoreAudio Aggregate | ScreenCaptureKit Audio Tap | SLA Threshold | Verdict |
| :--- | :--- | :--- | :--- | :--- |
| Audio Frame Drop Rate | 0.04% under thermal load | 0.00% (Zero dropped frames) | < 0.01% | 🟢 Superior |
| CPU Utilization (RSS) | 4.8% CPU / 45MB RAM | 1.8% CPU / 22MB RAM | < 5.0% CPU | 🟢 Superior |
| Permissions UX | Requires Virtual Audio Driver | Native macOS permission prompt | No kernel extensions | 🟢 Superior |
| Cold-Start Tap Latency | 480ms initialization | 45ms initialization | < 100ms | 🟢 Superior |

## 4. Key Discoveries & Implementation Pitfalls
- **Discovery 1:** ScreenCaptureKit seamlessly handles automatic audio sample rate resampling (e.g. 44.1kHz to 48kHz) in hardware with zero CPU penalty.
- **Pitfall 1:** If the user revokes Screen Recording permissions while an active session is recording, the tap fails silently unless registered with a dedicated delegate error handler.

## 5. Architectural Recommendation & Production Roadmap
> [!IMPORTANT] Recommendation: Adopt ScreenCaptureKit
> The prototype decisively proves ScreenCaptureKit is superior in CPU efficiency, audio frame reliability, and user onboarding simplicity.

- [ ] [[Systems Engineer Name]] Author formal Architecture Decision Record ([[ADR-0044]]).
- [ ] [[Lead Systems Eng]] Schedule migration of production audio capture pipeline for Sprint 26.
- [ ] [[Security Principal]] Update macOS permission request dialogues in user interface.

Filled Real-World Example

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

---
title: "Spike Debrief: SQLite FTS5 Tokenizer Evaluation"
date: 2026-10-04
spike_lead: "[[Alex Rivera]]"
recommended_path: Adopt Architecture
tags: [spike, sqlite, search]
---

# Spike Debrief: SQLite FTS5 Tokenizer Evaluation — October 4, 2026

## 1. Summary
Evaluated the `unicode61` tokenizer versus custom Porter stemmer for search queries across Markdown note collections.

## 2. Benchmark Results
`unicode61` with token diacritics enabled delivered 4.2ms P95 query times across a 15,000-document test vault with zero memory bloat.

## 3. Recommendation
Adopt standard SQLite FTS5 with `unicode61` tokenizer. Documented in [[ADR-0038]].

When to Use and When to Avoid

When to Use

• Use at the conclusion of time-boxed engineering research spikes and proof-of-concept prototypes.
• Use to document empirical benchmark data comparing alternative technical approaches.
• Use to establish the technical foundation for an Architecture Decision Record (ADR).

When to Avoid

• Avoid using for routine software feature implementation tasks with zero technical uncertainty.
• Avoid using for non-technical business strategy or marketing evaluations.

On-Device AI Integration

Summarize engineering spike debriefs with Oyma on macOS:

Analyze the technical spike debrief audio transcript:
1. Synthesize the framing hypothesis and core technical uncertainties explored.
2. Outline the prototyping methodology and stress-test conditions utilized.
3. Build a performance benchmark table comparing candidate architectures against SLA targets.
4. Record key technical discoveries, implementation pitfalls, and the final architectural recommendation.
Format in rigorous, engineering-grade CommonMark.

Your confidential technical research and architectural prototypes stay private on your Mac.