Odoo Workflow

Odoo Workflow - trace first, then code

Procedure for every Odoo change. The expensive failures are always the same: a field or method that does not exist, an xpath anchor that was never there, an override hooked on the wrong method, a stored field renamed without a migration, a sudo() nobody can audit, a test run that ran no tests. The fix is mechanical: no citation, no code.

When this applies

• Full path - anything that ends in Odoo Python, XML, JS or data: new field, override, inherited view, OWL patch, wizard, cron, controller, report, security, migration, bug fix, refactor, "optimize", "clean up". A pasted traceback starts here: its innermost frame in a workspace module is the first citation.
• Brief only - questions about Odoo symbols ("where is X defined", "does sale.order have F", "which model gets this field on 19"): run Steps 0-2 and answer with the Brief, no code.
• Fast path - the change names no symbol outside the module being edited and adds no field, override, xmlid, xpath, group or depends: a label, help text or typo in the module's own code, a manifest version bump, a test-only change. The Brief is one row citing the edited line; skip Steps 1, 3 and 6; Step 5 still applies (i18n when a string changed). Any doubt: full path.
• Skip for documentation-only and git-only tasks (use odoo-commit).
• Brainstorming and planning skills come after Step 2, and only if the business intent is still unclear - the Context Brief is their input.

Step 0 - Runtime, version, pack

The bundled helper scripts/odoo_trace.py (stdlib Python 3.8+, read-only) resolves the runtime and answers the Python-side trace questions. Call it with the skill's base directory written out in full every time - shell variables do not survive between tool calls. Below, odoo_trace stands for python3 <skill_dir>/scripts/odoo_trace.py.

odoo_trace env

First hit wins: flags, .claude/odoo.json, an odoo-bin configuration in .claude/launch.json whose addons cover the cwd (both files in the cwd or nearest parent), then the one *.conf whose addons_path covers the cwd, searched from the parent directory upwards (each level and its subdirectories). It prints version (from odoo/release.py), odoo_root, conf, python, dev_db, and the addons roots in the order Odoo uses them (the first root holding a module name wins). An odoo_version in .claude/odoo.json or a .odoo-version file must match release.py.

• Exit 2 prints SETUP ERROR: and the cause. Runtime not located: ask once for the core checkout and conf, pass them as odoo_trace --odoo-root <core> --conf <conf> <command> on every call (roots included), and offer to write a gitignored .claude/odoo.json with odoo_version, odoo_root, conf, python, dev_db (machine-local paths). Version sources that disagree, or several confs covering the cwd: ask which one is right. Never trace against custom roots alone.
• An explicit statement from the user or the project CLAUDE.md / AGENTS.md outranks the helper. If they disagree, stop and ask. Do not silently assume a version.
• Load the Odoo reference pack for that major: odoo-<major> with the skills CLI, <plugin>:odoo-<major>-0 in the Claude Code plugin (for example agent-skills:odoo-18-0). Read its references/api-highlights.md (APIs removed or renamed in this version) and only the guide section the task needs (grep -n '^## ' <guide>, then a range). Pack missing: say so and continue - the real source is the authority, never memory.

Step 1 - Trace the chain

Python symbols: the helper. It parses classes with ast, applies the version's _name rules, follows _inherit parents (mixins such as mail.thread, portal.mixin), _inherits delegation, base extensions and the core BaseModel, marks classes in files the module never imports (UNIMPORTED), and prints absolute file:line.

The last line is the VERDICT. Exit 0 = found, 1 = NOT FOUND (the verdict names the closest real symbols), 2 = setup error or answer unknown. Only exit 1 supports a NOT FOUND cell. Lists on hub models (sale.order, mail.thread) are capped; --all after model, method or unlisted prints them whole.

XML, JS, controllers, uses: grep over the same roots. ROOTS below means $(odoo_trace roots) written out in full: command substitution splits into one argument per root in zsh and bash, a plain $ROOTS string does not split in zsh. Keep the quotes around --include globs. A grep that warns No such file or directory or exits 2 is a broken command, never a NOT FOUND. So is a grep run while odoo_trace env exits 2 (an empty $(odoo_trace roots) leaves grep -r searching only the cwd), and one over a root whose path holds a space: it splits, and macOS grep skips the pieces silently, so grep that root separately, quoted.

# V1. Views on MODEL
grep -rlE --include='*.xml' "<field name=\"model\">MODEL</field>" ROOTS
# V2. Every view and QWeb template inheriting VIEW; -A1 also catches inherit_id split over two lines
grep -rnE -A1 --include='*.xml' "name=['\"]inherit_id['\"]|inherit_id=['\"]" ROOTS | grep -E ":[0-9]+:.*(ref|inherit_id)=['\"](MODULE\.)?VIEW['\"]|-[0-9]+-\s*ref=['\"](MODULE\.)?VIEW['\"]"
# V3. ANCHOR nodes inside one view record, absolute lines. A = the id line, B = the next </record>: grep -nE 'id="VIEW"|</record>' VIEW_FILE
awk -v a=A -v b=B 'NR>=a && NR<=b && /name="ANCHOR"/ {print FILENAME":"NR": "$0}' VIEW_FILE
# W1. OWL / QWeb client template: definition and every t-inherit (extension or primary)
grep -rnE --include='*.xml' "t-name=['\"]TEMPLATE['\"]|t-inherit=['\"]TEMPLATE['\"]" ROOTS
# W2. JS class or component: its definition (= import path) and every patch of it
grep -rnE --include='*.js' "^export (default )?(class|function|const) NAME[^A-Za-z0-9_]|patch\(\s*NAME[^A-Za-z0-9_]" ROOTS
# C1. Route (the second pattern finds a decorator split over lines), then every subclass of
#     its controller class (an `import CLASS as ALIAS` hit: run the class grep again with ALIAS)
grep -rnE --include='*.py' "@(http\.)?route\(.*['\"]URL['\"]|^\s*(route=)?\[?\s*['\"]URL['\"]" ROOTS
grep -rnE --include='*.py' "^class \w+\(([^)]*[ ,])?([A-Za-z_.]+\.)?CLASS[,)]|import.*[ ,]CLASS as " ROOTS
# S1. ACL rows and record rules on MODEL (dots as underscores)
grep -rn --include='ir.model.access.csv' "model_MODEL_UNDERSCORED," ROOTS
grep -rlE --include='*.xml' "model_MODEL_UNDERSCORED['\"]" ROOTS | grep security
# U1. Every use of NAME before renaming, removing, or changing the signature of a field or method
grep -rnwE --include='*.py' --include='*.xml' --include='*.js' --include='*.csv' --include='*.scss' "NAME" ROOTS
# T1. Tests to mirror
ls BASE_MODULE/tests/; grep -rnE "def test_.*METHOD" MODULE/tests

For U1 keep the hits on MODEL and list each one: views, QWeb, @api.depends, related=, domains, record rules, cron and server-action code, <function>, button name=, JS orm.call strings, tests, migrations. On a generic name (name, state, partner_id) restrict the list to the modules odoo_trace model MODEL printed plus the views from V1/V2; if it is still over 50 hits, show the count per module and ask before going on.

A grep hit counts only if its file loads (odoo_trace unlisted MODULE lists the files that never do) and, in Python, sits in MODEL's own class, not another class of the same file.

Reading budget - this is where tokens go:

• Read ranges, not files: Read with offset/limit, or awk 'NR>=A && NR<=B' - never sed -n 'A,Bp' | grep -n, whose line numbers restart at 1 and cannot be cited. At most 120 lines per hop.
• At most 3 hops inline. Deeper or cross-module flows go to the odoo-code-tracer agent with odoo_version, pack_dir (the loaded pack's directory), roots and helper (the helper's full path, plus any flags env needed), if it is installed; otherwise keep going with the commands above.
• Never re-read a file already cited in the Brief.

Step 2 - Context Brief (no citation, no code)

Write the brief before any code, one row per symbol the change touches (Odoo 18 example):

Layers: model / field / method+super / path / view+xpath / client / controller / security / company / data / migration / i18n / test.

The Source cell holds exactly one of:

• file:line - the cited line itself shows the claim (definition, record, anchor node).
• NOT FOUND - the helper exited 1, or a clean grep over all ROOTS matched nothing on MODEL. Name the closest real symbol when one exists.
• UNCERTAIN: <what is missing> - name the file not read, the runtime-built domain, or the other module's view that provides the anchor. Never for a question a command above answers.
• AMBIGUOUS: <modules> - overrides in modules that do not depend on each other.

Any cell other than file:line means no code for that row: drop it, add the missing depends, or ask. More than 15 rows means the task should be split; never drop a row to fit.

Rules:

• Redefined field. odoo_trace field lists every definition in load order; cite each one whose attributes the change relies on. Attributes not repeated keep their earlier value (selection_add extends the list), unless the newer class does not subclass the earlier one: then the earlier attributes are dropped and the helper prints final class.
• Path (related=, @api.depends, depends=, domain=, domain_force). One field call on the dotted path, one citation per hop. A missing hop, or a non-relational hop before the end, is NOT FOUND at that hop.
• Depends. A symbol defined only in a module outside odoo_trace depends MODULE is not guaranteed to be installed, even if it exists in the current database. Add the dependency or drop the row.
• Override order. Take it from odoo_trace method ... --module MODULE, never from memory or grep order: the class loaded last runs first and its super() reaches the earlier ones. Declare depends on every module whose override the change relies on. Pairs it marks AMBIGUOUS stay AMBIGUOUS.
• Xmlids. odoo_trace xmlid decides: a record in an XML or CSV file the manifest loads, or GENERATED at install (model_*, field_*__*, selection__*, base.module_*, account.<company id>_<name> from a chart template), each tied to the module the helper names. A record only in a file the manifest never loads is NOT FOUND (UNKNOWN when an init hook may load it). Never invent an xmlid and never report a generated one as missing. A missing group in a view's groups= does not stop the install: Odoo only logs a WARNING, and the node is hidden because no user belongs to a group that does not exist.
• Magic fields. Never assume them; odoo_trace field decides. create_uid, create_date, write_uid, write_date exist only when _log_access is true; it defaults to _auto, so report and SQL-view models (_auto = False) do not have them.
• Xpath anchor. The anchor must be in the base view or in an inheriting view of a module in depends; otherwise UNCERTAIN. A locator matches the first node, so state how many nodes carry that name in the combined views (V2 + V3).
• Company. If MODEL or a comodel has company_id, cite it and whether the model sets _check_company_auto. New relational fields to company-bound comodels get check_company=True. A new model with company_id gets a record rule as core writes it: [('company_id', 'in', company_ids)], or [('company_id', 'in', company_ids + [False])] when the company is optional.
• Schema change. Renaming, removing or retyping a stored field, changing or removing selection keys, adding required, adding a stored compute to a populated table, or renaming a model needs a migration row: the new manifest version and the migrations/<version>/pre-*.py / post-*.py script (def migrate(cr, version)) that moves the data; the script runs only if its version is above the installed one and not above the manifest's. A stored field renamed without one loses its column and data on -u, silently. Skip only when the user confirms the module was never installed on a database that matters. Recipes are in the pack's migration guide.
• sudo. Every added sudo() or with_user(SUPERUSER_ID) gets a security row: which ACL or record rule it bypasses (S1) and the check made before it (check_access / has_access on 18+, an access token, or a group check). No row, no sudo.
• Reuse over invent: before adding a field, helper, or compute, look for an existing one.
• "Clean code" / "stick to base" means: follow the base implementation's pattern with the minimal delta, never rewriting what super() already does. "Optimize" about speed means: measure first (query count or timing on a named case), change, measure again.