| name | odoo-doc-walkthrough |
| argument-hint | [module] [slug] |
| description | Author happy-path usage walkthroughs for an Odoo module: structured scenarios (name, role, precondition, steps {action/target/value}, expected outcome) grounded in the module's ACTUAL behavior via OSM. Dispatches odoo-doc-scenarist. Fire on: "write walkthrough for module", "document how to use this feature", "step-by-step user guide", "lập kịch bản sử dụng cho tính năng", "user workflow cho module", "hướng dẫn từng bước cho luồng", "viết kịch bản dùng chức năng". Standalone-first; OSM PRIMARY; no browser or instance needed; TEXT scenarios only. DO NOT trigger for: illustrated docs with screenshots or an RST user guide -> odoo-doc-illustration; a feature/menu inventory catalog -> odoo-doc-feature-map; executable test code (tours/HttpCase) -> odoo-test-writing; live UI QA + PASS/FAIL verdict -> odoo-acceptance; marketing/landing copy -> odoo-content-draft; architecture before implementation -> odoo-solution-design
|
Role
Documentation authoring for user-facing walkthroughs of an Odoo module - maps the module's
positive usage flows into readable, structured scenarios a new user can follow, grounded in what
the module ACTUALLY does, not in requirements or test oracles.
Standalone-first: OSM is the primary grounding source; no browser, live instance, or test
execution is needed to produce the walkthrough.
Out of Scope
- Executable test code (tours, HttpCase, pytest) ->
odoo-test-writing
- Live UI acceptance testing with a PASS/FAIL verdict ->
odoo-acceptance
- Marketing copy (landing page, email, social, App Store description) ->
odoo-content-draft
- Technical architecture or solution design before code is written ->
odoo-solution-design
- Negative / boundary / permission-violation test scenarios - those belong in
odoo-qa-suite or odoo-acceptance; this skill covers POSITIVE happy-path flows only
- Video or GIF recording of a live walkthrough ->
odoo-demo-recording
MCP tools
Pick the right tool first. Odoo Semantic (the odoo-semantic-mcp server) is the INDEXED Odoo source-code knowledge graph: a pre-built graph + vector index of Odoo source across every indexed Odoo version (legacy through latest) and repos/editions, with inheritance, override, and cross-module impact already resolved. It gives AUTHORITATIVE STRUCTURAL facts about how Odoo source IS DEFINED, with no local checkout needed. Unique signature: indexed, cross-version, inheritance-resolved, whole-graph, checkout-free. It is a STATIC index with NO runtime/live data.
This is your PRIMARY, context-efficient source for Odoo source/structure questions - the Odoo codebase is huge and reading it directly burns context, so prefer Odoo Semantic first. Order of precedence: (1) Odoo Semantic available -> use it; (2) available but it lacks the specific detail -> THEN read the source (Read/Grep your checkout) to fill that gap; (3) unavailable -> read the source. Reading code is the FALLBACK, never the first move when Odoo Semantic can answer.
Do NOT use Odoo Semantic for:
- LIVE DATA / runtime - actual record values, search/read/write real records, executing a method, this instance's installed modules -> use a live Odoo MCP server (one exposing read_record/search_records/execute_method), NOT Odoo Semantic.
Look-live-but-static tools (return indexed source, never runtime data): model_inspect, module_inspect, entity_lookup, validate_domain, validate_depends, validate_relation. These tool names look like they query a live instance but return indexed source data only. If you need live records, Odoo Semantic is the wrong server.
Session bootstrap (call once at session start):
set_active_version(odoo_version='17.0') - Pin a CONCRETE Odoo version (sentinels like 'auto' are rejected; the call doubles as a cheap reachability probe; 24h idle TTL).
Primary tools:
describe_module - Module manifest + defined/extended model counts + view/JS inventory in one call.module_inspect ★ - Module-level architecture overview: manifest summary, models defined/extended, views, OWL components, QWeb templates, JS patches, module dependency chain, or test class list in one call.model_inspect ★ - Superset inspection of an ORM model: enumerate or fully describe fields, methods, views, extenders, or a summary in one call.
Dispatch brief
Dispatch-brief skeleton. Fill the prompt below from the caller-side skeleton in
${CLAUDE_PLUGIN_ROOT}/snippets/dispatch-brief.md (read it by path) plus the Doc-writer family
delta; never inline that file verbatim into a hard-leaf brief.
Main dispatches odoo-doc-scenarist with (resolve <SHARE_DIR> once per
${CLAUDE_PLUGIN_ROOT}/snippets/state-root-resolution.md before filling CATALOG_PATH/OUTPUT_DIR
below; substitute the captured absolute path - never write the placeholder or a bare .odoo-ai/
into a Read/Write/Edit):
MODULE: <module technical name>
MODULE_PATH: <absolute path to module dir, if known>
ODOO_VERSION: <concrete series, e.g. 17.0>
SLUG: <short identifier for output paths, e.g. sale_order>
CATALOG_PATH: <SHARE_DIR>/documentation/<slug>/<module>/feature-catalog.jsonl (written by odoo-doc-feature-map; omit if not run)
OUTPUT_DIR: <SHARE_DIR>/documentation/<slug>/<module>/
USER LANGUAGE: <language for human-facing prose; identifiers stay English>
OUTPUT_DIR and CATALOG_PATH share the per-module subdir (<slug> = run id, <module> = module
technical name) so a multi-module run never collides on a flat walkthrough.jsonl/feature-catalog.jsonl,
and the scenarist reads the catalog from the exact path the feature-map phase wrote it (producer == consumer).
If MODULE_PATH is unknown, the scenarist resolves it from <SHARE_DIR>/context.md or disk.
If ODOO_VERSION is not stated, the scenarist infers it from the module manifest version
field major digit or from the addons directory name pattern; if still unresolved it returns
NEEDS_CONTEXT(odoo_version) before proceeding.
Collect walkthrough.md (and optional walkthrough.jsonl) from the agent output path, then
emit a Continuation Contract per ${CLAUDE_PLUGIN_ROOT}/snippets/continuation-contract.md.
Standalone-first fallback
When Odoo Semantic (the odoo-semantic-mcp server) is unreachable:
- Fall back to reading
__manifest__.py, model .py files, and view XML on disk to enumerate
menus, models, and key fields.
- Label the grounding in the output:
grounding: local-source.
- Emit
WARNING: OSM unreachable - scenario steps inferred from disk source; verify labels against a live instance before publishing.
When CATALOG_PATH is absent or the file does not exist:
- The scenarist derives the feature set directly from OSM
describe_module / module_inspect
(or disk fallback); the output is labeled catalog: none.
