171 lines
3.4 KiB
Markdown
171 lines
3.4 KiB
Markdown
# [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.
|