| 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.
