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

Deliver the confirmed outcome and keep the changed system correct. Investigate, repair, refactor, and verify only as far as one of these requires:

• a current requirement or accepted design decision;
• 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.

Keep implementation scope within those evidence-backed reasons and report unrelated debt separately.

Root-Cause Discipline

When an observed failure exists:

1. Reproduce or identify the failing observable condition.
2. Trace the responsible control, data, or state path until the cause is supported by evidence.
3. Correct the cause at the smallest responsibility boundary that preserves the governing contract.
4. Verify the original failure and the affected contract.

Stop causal questioning when the evidence supports the responsible path and its verification. Apply a direct correction when the cause and proof are already evident. Keep root-cause reasoning in the active task or response; create a separate artifact only for a named downstream consumer. Preserve error visibility and test strength, and correct the observed cause rather than masking it with an unconditional fallback or symptom patch.

Proportionate Impact Analysis

Before changing code, inspect the target and enough representative callers, consumers, tests, configuration, and siblings to determine:

• the contract being changed or preserved;
• the directly affected responsibility and dependency direction;
• the observable verification that can prove the outcome;
• any adjacent file required for the same outcome.

When the change alters a public, shared, serialized, or persistent contract and its consumers are enumerable, account for every known consumer. For other changes, representative inspection is sufficient. Stop expanding the search when additional context cannot change the implementation or verification decision. Record findings in the active task or response only when another worker needs them.