DECISIONS¶

Introduction¶

This document records the significant architectural and engineering decisions that explain why Renderflow looks the way it does.

Conformance¶

This document is authored in conformance with:

.github/specs/architecture/document.spec.md
.github/specs/architecture/governance/decisions.spec.md

Purpose & Scope¶

This document preserves high-value decisions, their rationale, relevant alternatives, and accepted trade-offs.

It does not serve as issue tracking, sprint notes, or brainstorming storage.

Definitions¶

Decision Record: a durable summary of a meaningful accepted choice.
Alternative: a plausible path that was considered but not adopted.
Trade-off: an accepted compromise made in service of a larger goal.
Status: whether a decision is active, evolving, or superseded.

Renderflow Decision Records¶

D-001: The primary interface is declarative specification¶

Status: Active
Decision: Renderflow centers workflow intent in YAML specifications instead of ad hoc shell procedures.
Rationale: Specifications are reviewable, portable, and durable. They let documentation, CI, contributors, and AI systems share one contract.
Alternatives considered: command-first operation, shell-script conventions, renderer-specific configuration.
Trade-offs: a declarative interface requires stronger normalization and documentation, but it scales better than procedural knowledge.
Related documents: PURPOSE.md, PRINCIPLES.md, ONTOLOGY.md

D-002: Transformation planning is modeled as a graph¶

Status: Active
Decision: Renderflow treats available conversions as a transform graph rather than only a linear sequence.
Rationale: Multi-format workflows, shared intermediates, and optimization modes require navigable path selection.
Alternatives considered: single fixed pipeline, per-output manual chaining.
Trade-offs: graph reasoning increases conceptual sophistication, but it enables reuse, explainability, and future extensibility.
Related documents: VISION.md, PILLARS.md, SYSTEM.md, ARCHITECTURE.md

D-003: Shared intermediate work is executed as a DAG¶

Status: Active
Decision: Multi-target work is merged into a DAG so shared intermediates execute once and feed dependent outputs.
Rationale: Reuse is both a performance and architectural clarity win; it matches the principle that shared work should be discovered and preserved.
Alternatives considered: independent per-target execution, hidden cache reuse without explicit planning.
Trade-offs: DAG execution introduces scheduling complexity, but it makes plan structure inspectable and efficient.
Related documents: FOUNDATIONS.md, SYSTEM.md, ARCHITECTURE.md

D-004: Deterministic caching and dry-run diagnostics are first-class¶

Status: Active
Decision: Renderflow treats cache-aware reuse and pre-execution visibility as architectural concerns, not optional polish.
Rationale: Trust depends on users being able to predict, inspect, and safely repeat work.
Alternatives considered: execution-only workflows, opaque caching, diagnostics as secondary output.
Trade-offs: stronger cache and diagnostic semantics require more explicit metadata, but they improve trust and maintainability.
Related documents: PRINCIPLES.md, FOUNDATIONS.md, DESIGN.md

D-005: Extensibility happens through registries and plugins¶

Status: Active
Decision: Renderflow expands through explicit transform contracts, metadata, and registries rather than patching core behavior for each specialized need.
Rationale: This preserves the integrity of the core model while allowing host applications and advanced users to extend capability.
Alternatives considered: core-only growth, hard-coded special cases, implicit binary discovery as the primary extension model.
Trade-offs: explicit extensibility requires clearer contracts and governance, but it avoids architectural drift.
Related documents: MANIFESTO.md, SYSTEM.md, ARCHITECTURE.md

D-006: AI participation is optional and governed¶

Status: Active
Decision: AI-assisted transforms and AI contributors are treated as bounded participants under human authority.
Rationale: AI can add leverage, but it must not redefine intent, bypass validation, or weaken trust.
Alternatives considered: AI-first automation, unrestricted provider-specific behavior, no AI integration at all.
Trade-offs: governance and optionality reduce convenience in some cases, but preserve safety, portability, and architectural clarity.
Related documents: PRINCIPLES.md, PERSONAL_MODEL.md, AI_CONSTITUTION.md, EPISTEMOLOGY.md

D-007: Distribution and documentation are part of architecture¶

Status: Active
Decision: Renderflow treats packaging, CI validation, release workflows, and documentation publication as part of how the architecture reaches users.
Rationale: Portability is not real unless the system can be installed, trusted, and understood across environments.
Alternatives considered: architecture limited to runtime code, ad hoc distribution channels, docs as secondary output.
Trade-offs: broader architectural scope requires more governance, but it keeps delivery aligned with purpose.
Related documents: PILLARS.md, METHODOLOGY.md, ROADMAP.md

Requirements, Constraints & Guidelines¶

Requirements¶

Significant decisions must include rationale.
Important trade-offs must be explicit.
Related architecture documents should be referenced where relevant.

Constraints¶

This document must not replace principles or roadmap.
Temporary implementation details must not be recorded as durable decisions.
Historical context should remain factual rather than speculative.

Guidelines¶

Explain why, not only what.
Keep records concise and durable.
Preserve context even if future revisions supersede a choice.

Authoring Contract¶

Purpose¶

Own Renderflow's architectural memory.

Responsibilities¶

This document owns:

accepted decisions,
rationale,
alternatives,
trade-offs,
historical context.

Non-Responsibilities¶

This document does not own:

architectural principles,
implementation details,
roadmap sequencing,
issue tracking.

Inputs¶

PRINCIPLES.md
FOUNDATIONS.md
SYSTEM.md
ARCHITECTURE.md
current repository behavior and workflows

Outputs¶

contributor onboarding
future architectural reviews
AI reasoning context
change evaluation

AI Generation Rules¶

AI systems should record decisions that are clearly evidenced by the current project and avoid inventing historical rationale where the repository does not support it.

Validation¶

A future contributor should be able to understand why major architectural moves were made.

Acceptance Criteria¶

Significant decisions are documented.
Every record includes rationale.
Trade-offs are visible.
The document preserves useful historical context without becoming an issue log.

AI Authoring Strategy¶

AI systems should:

inspect current architecture,
identify major accepted choices,
explain the rationale and alternatives,
stay factual and durable.

Rationale & Context¶

Renderflow contains deliberate choices that are not obvious from source alone: why it uses a declarative interface, why it models work as graphs and DAGs, why AI is optional, and why documentation and delivery are architectural concerns. This document preserves that reasoning.

Dependencies & External Integrations¶

Upstream Dependencies¶

PRINCIPLES.md
FOUNDATIONS.md
SYSTEM.md
ARCHITECTURE.md

Downstream Dependencies¶

onboarding
future decisions
implementation review
AI contributor reasoning

Examples & Edge Cases¶

Example¶

A contributor proposing hidden plugin auto-discovery can evaluate that proposal against D-005 and decide whether it weakens explicit extension boundaries.

Edge Case¶

If a future architecture replaces a current decision, the old record should remain with a superseded status rather than disappearing.

Validation Criteria¶

This document is valid when a new contributor can answer "why is Renderflow the way it is?" without mining commit history.

.github/specs/architecture/document.spec.md
.github/specs/architecture/governance/decisions.spec.md