ai-decision-record

AI Feature Decision Record

Iron Law: Do not proceed to implementation without a completed Decision Record written to docs/ai-decisions/<feature-slug>.md. It is a required artifact — not optional documentation.

Walk the user through filling out the Decision Record from the AI Playbook (Layer 3 §3.3). This is a required artifact before building any AI feature.

Procedure

1. Confirm the user is starting a new AI feature, not modifying an existing one. If modifying: load the existing Decision Record and update it; do not start fresh.
2. Ask the questions below one at a time. Do not skip ahead.
3. For each answer, validate it against the playbook's principles. Push back when:
   • The answer suggests AI is being added where deterministic code would work better (cross-check Layer 1 §1.6 Red Flag Matrix).
   • The risk tier proposed is lower than the blast radius justifies (cross-check Layer 2 §2.2 Autonomy Ladder).
   • The pattern (assistant / workflow / agent / autonomous) is more complex than needed (apply Layer 1 §1.4: start one tier below where you think you need to be).
   • No fallback is named.
   • No named human owner.
4. After all questions are answered, write the Decision Record to docs/ai-decisions/<feature-slug>.md in the repo (create the directory if needed).
5. Output a summary of the three biggest risks in the Decision Record and recommend whether to proceed, scope down, or rethink.

The questions

Ask these in order. Do not batch them. Wait for an answer before moving on.

1. What is the user problem this AI feature solves? (Not "what AI tech we're using" — what the user gets out of it.)
2. Why is deterministic code insufficient? (If you can't answer this in one sentence, the answer might be "it's not.")
3. Why is AI the right tool here? (Pattern recognition, ambiguity, ranking, summarization, etc. Map to Layer 1 §1.5 Green Light Matrix.)
4. What pattern fits: assistant, workflow, agent, or autonomous? (Default to the lower tier. Most "agent" problems are workflows.)
5. What is the risk tier (0–5)? (Reference Layer 2 §2.2 Autonomy Ladder. Sum blast radius across a session, not per action.)
6. What is the fallback when AI fails? (Timeout, vendor outage, low confidence, schema violation → what happens? A specific deterministic path.)
7. What is the primary eval metric and target value?
8. How large is the eval set and where does it come from? (Default floor is 100; check Layer 2 §2.14 for risk-tiered minimums.)
9. What gets human review? Who reviews it? What's the SLA? (Reference Layer 2 §2.1 default SLA table.)
10. What is the cost ceiling per task? (Reference Layer 2 §2.10 cost tiers.)
11. What is the p95 latency target?
12. Which model? Smallest viable, or routing strategy with fallback? (Reference Layer 2 §2.9.)
13. Has a security review covered prompt injection, tool-output injection, exfiltration, and tenant isolation? (Reference Layer 2 §2.5.)
14. Has a data governance review covered: what enters context, what's logged, retention, training-use, tenant isolation, deletion propagation? (Reference Layer 2 §2.13.)
15. Where is the kill switch / feature flag? Has it been tested? (Reference Layer 4 §4.4.)
16. What is the rollback plan?
17. What is the 12-month AI tax estimate? (Model spend + evals + review queue + observability + drift fighting + security + compliance + on-call. Reference Layer 2 §2.11.)
18. Who is the named human owner — not a team, a person — accountable for the eval metric?