orient-before-edit

name

orient-before-edit

description

Use BEFORE a non-trivial or unfamiliar change, when unsure which module owns the behavior — and BEFORE diving into a fix when prior reports may already describe the area. Build a pre-edit structure brief over both the source tree and the reports directory so candidate owners and prior investigations surface together; CONFIRM the owner by searching and reading before committing to it. Then deliver the change in isolation. Trigger on "where should this go", "did anyone already look at this", "what's the context".

Orient before editing, then deliver in isolation

Two phases: learn the structure (and what is already known) before touching code, then apply the change so the canonical branch only ever receives finished, verified commits.

Phase 1 — Orient

Build a pre-edit structure brief over the area you intend to change. The brief should cover both directories that hold relevant context:

• the canonical source tree (typically source/) — for owner ranking and required preflight reading;
• the reports directory (typically reports/) — for prior investigations of the same purpose, and for problem tickets opened by earlier fix-as-poc runs that sit in a related subtree.

Run the orientation tool over both paths in one invocation so the ranking and the knowledge sources are computed against the same task description. Pass the failing command output, the symptom, or the change description as the task prompt; the tool's vector match against reports/<purpose>/README.md files is what surfaces relevant prior work.

From the output, read:

• Candidate owners — a ranking, not the answer. The top entry is often noise: verbose support files (lint rules, configs, generated code) can outrank the real domain module. Skip non-domain directories; take the first plausible domain owner.
• Knowledge sources — reports/.../README.md entries are NOT implementation targets, but they often contain the diagnosis you would otherwise re-derive. Read at least the matching report before opening product code.
• Files to read first — the most reliable signal for owner confirmation.
• Locations that must not hold domain behavior.
• Callers / context — not implementation targets.

Confirm the owner by searching for the relevant symbol and reading the candidate files before deciding. The ranking is a pointer; your reading is the decision. On a small or already-familiar area, skip the ranking and read the code directly — orienting pays off most on large, unfamiliar trees and on fixes whose root cause spans multiple investigations.

Phase 2 — Deliver

Implement in the confirmed owner, then integrate via the isolate → verify → cherry-pick operation (the isolate-and-integrate skill). Never edit the canonical branch directly.

For a bug fix, route the work through fix-as-poc: open a reports/<purpose>/README.md problem ticket first, then enter the isolation loop. The orient brief produced in Phase 1 belongs in the ticket's "diagnosis" section as evidence.

Re-run the orientation after a change that moves ownership, so the next pass starts from reality. Re-run it after closing a report, so the next agent's brief sees the updated knowledge surface.

The exact orientation command (binary name, flags, paths to scan) is project-specific — see the project's CLAUDE.md. This skill is the method; the project supplies the verbs.