# AI Execution Workflow

> The official lifecycle every AI assistant follows on a task in this project.

_Governance layer. Verified 2026-07-23. See [`../README.md`](../README.md)._

---

## Lifecycle

```
Understand
  ↓
Load relevant context from docs/ai   (see task-classification.md + context-loading.md)
  ↓
Inspect implementation                (read the authoritative code the KB names)
  ↓
Create implementation plan
  ↓
Request confirmation for architectural changes   (see decision-process.md)
  ↓
Implement                             (respect change-management.md + agent-rules.md)
  ↓
Test                                  (see ../05-development/testing.md)
  ↓
Update documentation when required    (only affected KB files, after Review & Verify)
```

This mirrors the Engineering Platform's AI Loading Order, specialized for Numu.

## When AI must inspect code
- **Before changing any behavior** — the KB orients; the code is authoritative. Each KB doc names its source files (e.g. `McpToolRegistry`, `Startup/InvestorLabelActionService`).
- When a KB statement is marked **`Unknown - requires confirmation`** and the task depends on it.
- When touching a **canonical path** (action services, `ActionPolicyService`, `McpAuth`) — read the real implementation, do not rely on the summary alone.

## When AI must ask before changing
Request confirmation (and, if accepted, record a decision) before:
- Any **architectural change** — new/changed boundary, layer, or contract ([`../01-architecture/`](../01-architecture/)).
- Anything touching a **locked decision** — e.g. DR-001 execution ownership ([`../06-history/decisions-log.md`](../06-history/decisions-log.md)).
- Adding a **new AI action or MCP tool**, or widening **permissions/scopes** ([`../03-ai-agents/permissions.md`](../03-ai-agents/permissions.md)).
- Adding/altering an **external integration** ([`../04-integrations/`](../04-integrations/)).
- Any **schema change**, or work that could affect **production data**.
- Introducing a concept the KB marks as **not decided** (e.g. a `Deal` entity — [`../02-business/deals.md`](../02-business/deals.md)).

## When KB updates are mandatory
Documentation follows **verified** code — never updated before Review. Update only the affected files:

| Change | Update |
|--------|--------|
| Business rule / domain behavior | the relevant [`../02-business/*`](../02-business/) + a decision record |
| Architecture / boundary | [`../01-architecture/*`](../01-architecture/) + [`decision-process.md`](decision-process.md) |
| New/changed AI action, tool, or permission | [`../03-ai-agents/{actions,tools,permissions}.md`](../03-ai-agents/) + decision record |
| Schema change | [`../05-development/database-rules.md`](../05-development/database-rules.md) + [`../06-history/migrations.md`](../06-history/migrations.md) |
| New/changed integration | [`../04-integrations/*`](../04-integrations/) + [`../01-architecture/integrations.md`](../01-architecture/integrations.md) |
| Any significant decision | [`../06-history/decisions-log.md`](../06-history/decisions-log.md) |

If a task changes nothing documented here, **state that explicitly** in the final report.