A comprehensive playbook for a solo developer rebuilding the NVT Long‑Term Yield (LTY) web application in React 19 with AI assistance. It establishes a mental model that treats the AI as a stateless implementation assistant, requiring explicit context injection for every session. The guide defines a permanent .ai directory containing five core markdown files (ARCHITECTURE.md, PATTERNS.md, TRANSLATIONS.md, CALCULATIONCONTRACTS.md, MODULEMAP.md) that capture stack decisions, reusable patterns, C#‑to‑React concept mappings, numerical contracts, and ticket‑to‑module status. Every AI session starts with a strict header that lists the stack, active module, required patterns, and prohibited actions. The workflow is organized into five “waves” of module sequencing: Wave 1 ports a core calculation module and its display component; Wave 2 builds routing and shared UI primitives; Wave 3 delivers the large MET data table; Wave 4 adds filters, charts, and advanced options; Wave 5 finalizes quality and single‑site tabs. Context‑window management is enforced by never crossing module boundaries without injecting the dependent module’s public TypeScript interface and a usage example, and by limiting sessions to a single vertical slice (component + hook + types) with a restart after ~30‑40 back‑and‑forth turns. A central guardrail is the live C#/Xamarin reference app: the guide outlines a three‑layer validation protocol (published harvest reports, live UI screenshots, edge‑case documentation) and requires known input‑output pairs to be recorded in CALCULATION_CONTRACTS.md, forcing the AI to generate code that matches ground‑truth values. Human review checkpoints replace missing QA automation: a pre‑session spec sentence, a “green‑path” verification (render, interaction, calculation match, TypeScript compile), a full‑module review (pattern adherence, library drift, duplicated logic), and a periodic architectural oversight sync that reviews decisions rather than line‑by‑line code. The document enumerates practical failure modes (architectural amnesia, interface hallucination, calculation drift, scope creep, test case bypass, context overflow) with concrete mitigations. It then drills down into the NVT LTY domain, mapping the legacy feature set into concrete React modules (data fetching layer, location selector, MET table, filter bar, performance chart, advanced options, quality/single‑site tabs) and highlighting domain‑specific risks such as floating‑point divergence, predicted‑vs‑actual flag handling, and multi‑location averaging that must stay server‑side. A detailed React 19 migration checklist covers toolchain migration (Vite/Next.js, CRA deprecation), required codemods, library compatibility, and removal of deprecated APIs (forwardRef, ReactDOM.render, defaultProps, string refs). It recommends adopting React 19 features (useActionState, useOptimistic, use() with Suspense, optional React Compiler, resource preloading) and provides a performance validation checklist (virtualisation with TanStack Virtual, re‑render profiling, Core Web Vitals targets). Security reminders about RSC patches and dependency lock‑file audits conclude the guide.
Topics
Core Mental Model: AI as an Amnesiac Implementation Assistant
Reframes the AI’s role as a stateless code generator that requires explicit context injection for every session, establishing the foundation for all subsequent workflow steps.
Pre‑Build Context Infrastructure (.ai Directory)
Defines five canonical markdown files (ARCHITECTURE, PATTERNS, TRANSLATIONS, CALCULATION_CONTRACTS, MODULE_MAP) that serve as the permanent knowledge base injected into each AI prompt.
Wave‑Based Module Sequencing to Prove the Process Early
A five‑wave plan (core calculation, routing, MET table, filters/charts, advanced options) that delivers a green‑flag module before scaling effort.
Context Window Management and Contract‑First Interfaces
Guidelines to never cross module boundaries without injecting the dependent module’s public TypeScript interface and a usage example; limits session size to ~30‑40 turns.
Reference App as Hallucination Guardrail
Three‑layer validation (harvest reports, live UI screenshots, edge‑case docs) and embedding known input‑output pairs in CALCULATION_CONTRACTS to force correct code generation.
Human Review Checkpoints in Absence of QA Automation
Four structured checkpoints: pre‑session spec, green‑path verification, module completion review, and periodic architectural oversight sync.
Practical Failure Modes and Mitigations
Enumerates six common failure modes (architectural amnesia, interface hallucination, calculation drift, scope creep, test bypass, context overflow) with concrete mitigations.
NVT LTY Domain‑Specific Module Decomposition
Maps the legacy feature set into concrete React modules (data fetching, location selector, MET table, filter bar, chart, advanced options, quality tabs) and highlights domain‑specific risks.