engineering-flow

Engineering Flow

Engineering standards, decision pipelines, and code hygiene rules.

---

Delivery Principles

Ship working software in small, verifiable increments:

• Keep changes scoped to a single logical objective.
• Avoid speculative abstractions and overengineering.
• Implement thin, vertical slices from entrypoint to persistence.
• Verify each slice with automated tests and compiler checks before proceeding.

---

Design Pipeline: RFCs and ADRs

Separate exploration from permanent architectural choices:

graph TD
    A[Ambiguous Goal / High Uncertainty] --> B[RFC in design/rfc/]
    B -->|Consensus Reached| C[ADR in design/adr/]
    C --> D[Implementation Tasks]
    E[Trivial / Low-Uncertainty Task] --> D

• RFCs (design/rfc/): Use during exploration when requirements are ambiguous, trade-offs need debate, or multiple viable architectures exist. RFCs are fluid working documents.
• ADRs (design/adr/): Use to record finalized decisions. ADRs are immutable historical logs capturing context, chosen architecture, and accepted trade-offs.
• Tasks: Break ADR conclusions into concrete checklist items with clear acceptance criteria.

---

Task Prioritization

Categorize work by technical certainty and business value:

	High Technical Certainty	Low Technical Certainty
High Value	Direct execution: Implement interactively with compiler feedback and tight test loops.	Research & Spikes: Do not write production code yet. Run throwaway spikes in scratch/ or draft an RFC.
Low Value	Delegate: Offload to background tasks or subagents.	Defer / Discard: Drop or postpone until certainty increases or value is demonstrated.

---

Research & Evidence Hierarchy

Do not guess APIs, package syntax, or model behaviors. Ground technical decisions in primary sources:

[1] Source Code (highest authority)
  └── [2] Official Documentation & API Reference
        └── [3] Official Release Notes & Announcements
              └── [4] Industry Expert Articles (< 3 months old)
                    └── [5] Community Posts (< 3 months old)
                          └── [6] Stale Articles (> 3 months old — discard)
                                └── [7] Social Media (unverified — cross-check first)