Skip to content

Dev-Mode Orientation

Forced orientation before dev work — activate dev mode, search the knowledge store for the subsystem being modified, read the code, then declare the prior art found. Only after advancing the step with a non-trivial declaration may the agent proceed with the actual task.

Workflow name: dev-orient

Workflow ID: wfd_c99d10fc215d4a79942c6c812d95bb9b

Execution: main

Override not allowed

Steps

# ID Name Type Depends on
1 orient Search, read, and declare prior art reasoning

Step instructions

orient

(main, reasoning)

Before touching code, orient on the subsystem you are about to modify. The default dev failure mode is acting on general knowledge without consulting the codebase — this workflow exists because agents (including the one that most recently created it) have skipped this step and written wrong code as a result.

Required actions

  1. Activate dev mode so dev_notes surface in subsequent knowledge queries:
`mcp__work-buddy__wb_run("mode_toggle", {"mode_id": "dev", "active": true})`

  1. Identify the subsystem you are about to modify in one short phrase (for your own framing; not submitted as output).

  2. Issue at least one agent_docs call targeting that subsystem at depth="full". Prefer scope browsing if you do not know the exact path:

  3. Exact: mcp__work-buddy__wb_run("agent_docs", {"path": "architecture/embedding-service", "depth": "full"})

  4. Browse: mcp__work-buddy__wb_run("agent_docs", {"scope": "architecture/"})

  5. Search: mcp__work-buddy__wb_run("agent_docs", {"query": "<natural-language question>"})

  6. Open the relevant code files — not just headers, read them. Identify existing wrappers, classes, or functions that already solve part of the problem. If the subsystem has tests, at least skim their shape.

When the change affects a dashboard user task, navigation, control, information presentation, feedback, recovery, or user-visible behavior, load dev/dashboard/ux-directions before deciding the interaction design and dev/dashboard/verification-directions before opening a browser. Include Python changes that alter generated surfaces, such as health registrations that appear in Settings. Populate optional affected_surfaces, required_reviews, and review_scope lists. Reassess when scope changes. For unrelated work leave these lists empty and do not perform a dashboard review. Reading dashboard code for an unrelated investigation does not itself require a review.

  1. Advance this step via wb_advance with a dict in this exact shape. Empty or trivial lists are a signal you have not oriented — go deeper and try again:
{
  "units_read":     ["<path/to/unit>", ...],
  "files_read":     ["<repo-relative/or/absolute/path>", ...],
  "wrappers_found": ["<existing function/class/capability>", ...],
  "affected_surfaces": ["dashboard:cowork"],
  "required_reviews": ["dashboard-ux"],
  "review_scope": ["Create a document, correct its title, and find it after reload"]
}

If you are tempted to skip

That is the exact signal you need this step most. Your feeling of already-understanding is how previous dev agents have ended up writing wrong code. The cost of a minute of discovery is trivial against the cost of a wrong commit. Orient anyway.

What this step does NOT require

  • A long prose analysis — the three lists are enough.
  • Reading every file in the subsystem — just the ones load-bearing for the change.
  • Loading every related knowledge unit — one or two at depth="full" is usually the right amount.

Only after advancing with a non-trivial declaration may you return to the user and proceed with the actual dev task.