# [System or Workstream Name] - First Principles and Product Understanding

**Date:** [YYYY-MM-DD]  
**Status:** [Draft | In Review | Approved]  
**Owner:** [Name]  
**Reviewers:** [Names]  
**Scope:** [Subsystem, mission class, runtime layer, or product surface]  
**Purpose:** Define the problem, intended product behavior, and architectural logic from first principles before implementation begins.

## Executive Summary

State:

- what this system is
- why it matters
- why current architecture is insufficient
- what the target improvement is

## Assumptions and Constraints

### Assumptions

State the assumptions that must be true for this design to hold.

### Constraints

State the technical, organizational, legal, runtime, and infrastructure constraints that shape the solution.

## Reference Sources and Rationale

### Local Sources

List:

- current repo files
- existing design docs
- prior integration artifacts

Explain why each source matters.

### Upstream or External Sources

List:

- upstream frameworks
- public reference repos
- external standards or papers if used

Explain what is being borrowed and what is not.

## Problem Statement

Describe the underlying problem in plain terms:

- current failure mode
- why it exists
- what business or product damage it causes
- why the current team cannot just “work around” it forever

## System Vision

Describe the intended end state:

- operator experience
- internal execution model
- auditability and safety expectations
- where this system fits inside Project Velocity

## Core Metaphor or Design Lens

If using a metaphor such as biomimicry, define:

- the mapping from metaphor to real system parts
- what the metaphor clarifies
- what the metaphor must not be allowed to distort

## First-Principles Architecture

Document the foundational principles that should govern all implementation.

### Principle 1

Name the principle and explain:

- what it means
- why it matters
- what tradeoff it creates

### Principle 2

Repeat.

### Principle 3

Repeat.

Add as many principles as the work requires.

## Functional Architecture and Key Roles

Describe the main runtime layers and their responsibilities.

For each role or layer, state:

- purpose
- inputs
- outputs
- hard boundaries
- failure modes

## Data Model and Interfaces

List the major internal artifacts or interfaces that this system depends on.

For each artifact, describe:

- identity fields
- producer
- consumer
- why it exists

## Interaction and Workflow Description

Describe the standard operational flow from input to output.

Then describe:

- exceptional flows
- failure handling
- review or escalation path

## Improvements and Recommendations

List the recommended design improvements over a naive implementation.

For each improvement, explain:

- what changes
- why it is better
- what it costs

## Migration and Fork Strategy

Describe:

- what to reuse
- what to fork
- what not to inherit
- how to preserve provenance and licensing clarity

## What This Means for Project Velocity

State the direct product and implementation implications:

- what becomes easier
- what becomes safer
- what becomes sellable
- what still remains out of scope

## Recommended Initial Scope

Define the minimum mission classes, modules, or surfaces to start with.

## Open Questions

List the unresolved issues that need explicit follow-up.

## Bottom Line

Summarize the design truth in one or two paragraphs.