ai-development-guide

AI Development Guide

Reference

Read references/frontend.md only for React or TypeScript frontend work whose changed behavior or quality failure needs those rules.

Outcome Boundary

Ground the required outcome in the governing task or design sources and the user's explicit instructions. Choose work by what the consumer must be able to do or judge, preserving that result while reducing the means needed to deliver it.

When an unverified premise could invalidate the approach, check it by the cheapest sufficient means before expanding dependent work. When results contradict that premise, reconsider the approach before patching its parts. Keep this reasoning in the current task; a small request needs no additional artifact.

Phase passage permits progress; technical necessity remains a separate evidence-backed lifecycle decision. Reconsider and remove or supersede means recorded in a Design Doc, ADR, plan, AC, or test when the required outcome remains satisfied. Preserve user-required outcomes, explicit constraints, actual consumer contracts, and external-action authority. For authorized feature removal, check remaining consumers; the removed entry point and its now-unused backend create no preservation obligation. Coordinate affected source and consumer updates through the orchestrator; existing execution authority continues for outcome-preserving technical reductions.

Investigate, repair, refactor, and verify only as far as one of these requires:

• a user-required outcome or explicit constraint;
• a dependency needed for that outcome;
• an observed failure or contradiction in the changed path;
• an evidence-backed material risk created or exposed by the change.

Evidence makes a candidate evaluable. Adopt work only when it is necessary now and its benefit justifies total lifecycle cost over no change, subtraction, or reuse. A required outcome defect still needs a sufficient response. Keep unrelated debt outside the change.

Root-Cause Discipline