Strategy
Defines what is worth building—and why.
System 02 · Evidence, specification & decision memory
The Knowledge System
The authoritative layer that converts approved strategy into what is known, assumed, decided, and required—while preserving why the team believes it.
Knowledge
Defines what is known, assumed, decided, and required.
Execution
Turns approved knowledge into tested software and hardware.
01 · Responsibilities
Nine questions before execution begins
The Knowledge System creates an authoritative description of what must be true—and prevents agents from silently converting plausible guesses into requirements.
Approved strategy version and constraints.
Verified facts and supporting evidence.
Assumptions, confidence, and validation plans.
Decision, rationale, owner, and alternatives.
Functional requirements and behaviors.
Quality attributes and measurable thresholds.
APIs, protocols, data formats, and hardware contracts.
Acceptance criteria and validation methods.
Versioned deltas and downstream impact.
02 · Artifacts
A connected Knowledge Package
Small, linked artifacts replace one oversized design document and become the authoritative input contract for Execution.
| Artifact | Purpose | Required content |
|---|---|---|
| Context Map | Defines the environment | Actors, systems, hardware, dependencies, boundaries |
| Domain Model | Creates shared language | Entities, states, rules, relationships, glossary |
| Evidence Register | Records verified information | Claim, source, date, confidence, applicability |
| Assumption Register | Makes uncertainty visible | Assumption, risk, owner, validation plan, status |
| Decision Records | Preserves reasoning | Decision, alternatives, rationale, consequences |
| Requirement Set | Defines required behavior | Requirement, source, priority, acceptance criteria |
| Quality Attribute Model | Defines operational expectations | Performance, reliability, memory, safety, usability |
| Interface Contracts | Protects boundaries | Inputs, outputs, timing, errors, ownership, compatibility |
| OpenSpec Changes | Defines approved increments | Proposal, specification delta, tasks, approval |
| Traceability Map | Connects the lifecycle | Strategy → requirement → design → code → test → evidence |
| Knowledge Delta | Captures learning | New fact, invalidated assumption, affected artifacts |
03 · Classification
Every important statement declares what kind of truth it is
Epistemic status tells agents whether a statement can authorize implementation. Plausibility is never treated as proof.
| Status | Meaning | May authorize implementation? |
|---|---|---|
| Observed | Directly measured or reproduced | Yes, within stated conditions |
| Verified | Confirmed through trusted evidence | Yes |
| Decided | Chosen by an authorized owner | Yes |
| Required | Mandated by an approved source | Yes |
| Assumed | Believed but not yet validated | Only when risk is accepted |
| Proposed | Suggested but not approved | No |
| Unknown | Information is missing | No, if correctness is affected |
| Superseded | Replaced by a newer artifact | No |
Common metadata
Minimum knowledge contract
Any claim that can affect implementation must expose its source, status, owner, authority, freshness, and validation path.
- Identity, version, and approval state
- Strategy lineage and applicability
- Knowledge status, confidence, and risk
- Acceptance criteria and validation method
- Dependencies, evidence, and review history
artifact_id: REQ-LIFECYCLE-003
artifact_type: requirement
title: Resume restores paused state
version: 0.4
status: approved
owner: gameplay-system-owner
source_strategy: STRAT-RP2350-001@0.3
knowledge_status: required
confidence: high
risk_level: medium
dependencies: [ADR-007, IFACE-INPUT-002]
acceptance_criteria:
- Restore within one rendered frame
- No simulation time elapses while paused
validation_method:
- automated-state-test
- hardware-in-the-loop-test04 · Lifecycle
Approved knowledge remains challengeable
Measurements and implementation discoveries can reveal that an assumption is false or a requirement is infeasible. They trigger controlled change; they never silently rewrite truth.
Captured
Classified
Proposed
Reviewed
Approved
Active
Challenged
Revalidated
Controlled learning loop: Revalidated knowledge returns to Active or becomes Superseded, with downstream impact recorded.
05 · OpenSpec
The change-control engine inside Knowledge
OpenSpec manages the path from investigation to approved, executable knowledge. Apply is the controlled bridge into Execution.
Explore
Investigate the system, identify unknowns, and gather evidence without authorizing implementation.
Propose
Describe the change, specification delta, platform consequences, and acceptance criteria.
Refine
Resolve ambiguity, validate feasibility, and separate platform from game behavior.
Approve
Humans authorize a specific knowledge package and version.
Apply
Convert approved knowledge into bounded work packages linked to implementation evidence.
06 · Validation
Evidence must match the claim
Authority comes from appropriate, repeatable evidence—not documentation volume.
| Claim type | Preferred evidence |
|---|---|
| Hardware capability | Datasheet plus target-board measurement |
| Timing or performance | Repeatable benchmark on target hardware |
| User experience | Prototype review or user observation |
| API behavior | Interface contract and automated contract test |
| Architectural decision | Decision record and impacted-system review |
| Safety constraint | Authoritative source and qualified human approval |
| Game rule | Approved design specification and behavior test |
| AI recommendation | Independent verification appropriate to risk |
For RP2350 development, target hardware outranks simulation and desktop-only results whenever they conflict.
07 · Quality
Requirements that agents can execute safely
Good requirements are atomic, testable, bounded, traceable, owned, versioned, implementation-neutral where possible, and explicit about timing and edge cases.
Quality rules
- One observable obligation per requirement
- Explicit pass/fail criteria
- Scope and operating conditions stated
- Link to an approved strategic source
- Owner accountable for correctness
- Version history preserved
- Errors, timing, and edge cases included
From intent to measurable behavior
Weak
“Pause should feel immediate.”
Stronger
After valid pause input during Running, enter Paused before the next simulation update and render the paused presentation within one display frame.
08 · Governance
Humans own meaning, risk, and boundaries
AI can draft, classify, compare, and challenge knowledge. It cannot grant authority to its own output.
Human authority
Product OwnerUser behavior, priorities, and acceptance.
Chief ArchitectArchitectural coherence and technical constraints.
Engine StewardPlatform boundaries and interface stability.
Engineering LeadsGameplay, embedded, QA, and asset-pipeline truth.
AI-enabled work
ChatGPTExplore, structure knowledge, expose contradictions.
OpenSpecManage proposed and approved specification changes.
CodexMaintain traceability and coordinate approved execution.
AgentsConsume approved knowledge; report conflicts and discoveries.
Authorization checkpoint
Knowledge Gate
Execution remains blocked until the package is clear, measurable, traceable, reviewable, and safe to convert into bounded work.
Approved strategy version referenced
Affected product and platform capabilities identified
Requirements atomic, clear, and testable
Critical interfaces explicitly contracted
Quality thresholds measurable
Assumptions validated or consciously accepted
Blocking unknowns resolved
Platform impact reviewed by Engine Steward
Acceptance criteria and validation methods defined
Human approvals reference identical artifact versions
gate: knowledge-approval
decision: approved
authorized_next_stage: openspec-apply
change: CHANGE-GAME-LIFECYCLE-001@0.4
strategy_source: STRAT-RP2350-001@0.3
conditions:
- verify frame timing on target board
- capture 100 pause/resume cycles
accepted_risks:
- audio resume latency not optimized
approved_by:
- product-owner
- chief-architect
- engine-steward09 · Reference case
RP2350 start, pause & resume
A concrete Knowledge Package defines the state model, valid transitions, pause/resume contracts, and evidence required before lifecycle behavior becomes platform truth.
Booting
Ready
Running
Paused
Game Over
Fault
| Current state | Event | Result |
|---|---|---|
| Ready | Start | Running |
| Running | Pause | Paused |
| Paused | Resume | Running |
| Running | End condition | Game Over |
| Game Over | Restart | Running |
| Any active state | Unrecoverable error | Fault |
Every unspecified transition is rejected and logged.
Pause contract
- Simulation time stops
- Entity, score, and streak remain unchanged
- Input is limited to permitted paused actions
- Pause overlay appears
- Audio follows the approved state policy
- Rendering may continue without gameplay advance
Resume contract
- Prior gameplay state is restored
- Paused duration does not affect simulation timers
- No input event is duplicated
- RNG continuity is preserved when required
- Audio resumes by defined policy
- Update begins at the captured simulation boundary
Required evidence
- Automated state-transition tests
- Invalid-transition tests
- Deterministic state comparison
- Target-board frame timing
- 100 pause/resume cycles
- Input and audio stability observations
10 · Repository
Git as the source of knowledge truth
Durable specifications remain separate from generated validation output, while immutable references preserve full traceability.
Knowledge lives with the system
Specifications, decisions, assumptions, and interface contracts are versioned beside the software they govern.
Generated output belongs under validation/evidence/; the Knowledge System retains immutable references to the applicable evidence and specification version.
Next design step: define the common knowledge schema and classification policy.
knowledge/
├── context/
│ ├── system-context.md
│ └── hardware-context.md
├── domain/
│ ├── glossary.md
│ └── state-models/
├── evidence/
│ └── evidence-register.yaml
├── assumptions/
│ └── assumption-register.yaml
├── decisions/adr/
├── requirements/
│ ├── product/
│ ├── platform/
│ └── quality/
├── interfaces/
├── openspec/
│ ├── changes/
│ └── approved/
├── traceability/
│ └── traceability-map.yaml
└── learning/
└── knowledge-deltas/