atlas-locate
Phase L (Locate) — bounded probes and scatter subagents to answer DECISION_TARGET sub-questions. Descends a symbol → graph → lexical → windowed-read → test-dry-run ladder; emits FINDING-XXX records with evidence anchors and confidence tiers. Hot phase (≤60% of mission budget). Use after map.md is complete and sub-questions remain. Trigger phrases — "find where X happens", "trace Y", "who writes to Z", "who calls this", "what implements this".
- License 许可
- Apache-2.0
- 所属仓库
- Rynaro/magicite
- 最近更新
- 2026-10-14
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- atlas-locate
- metadata
- { "phase": "L", "methodology": "ATLAS" }
- description
- Phase L (Locate) — bounded probes and scatter subagents to answer DECISION_TARGET sub-questions. Descends a symbol → graph → lexical → windowed-read → test-dry-run ladder; emits FINDING-XXX records with evidence anchors and confidence tiers. Hot phase (≤60% of mission budget). Use after map.md is complete and sub-questions remain. Trigger phrases — "find where X happens", "trace Y", "who writes to Z", "who calls this", "what implements this".
- allowed-tools
- search_symbol graph_query search_text view_file test_dry_run memex_read
03 SKILL.md 正文
SKILL: Locate — bounded probes & scatter subagents (Phase L)
When to use
Load when: map.md is complete and sub-questions exist against DECISION_TARGET.
Unload when: every sub-question has a FINDING-XXX at confidence ≥ M or is
recorded in GAPS.
Contract
| Field | Value |
|---|---|
| LLM calls permitted | Yes, but at the synthesis edge only. Retrieval remains deterministic-first. |
| Tool budget | ≤ 60% of mission max_tool_calls — this is the hot phase |
| Output | findings.md — list of FINDING-XXX records, each schema-valid |
Probe ladder
For every sub-question, descend this ladder. Stop at the first tier that produces a confident answer.
Tier 1 — Symbol probe (deterministic)
search_symbol(name="CastVoteRecord")
→ definition site
→ all references (with path:line)
→ subclasses / implementers
→ method definitions on the symbol
This is a constant-cost index lookup. Use it whenever the sub-question references a named thing (class, method, constant, config key).
Tier 2 — Graph query (deterministic)
graph_query("callers_of: RecordVote#call")
graph_query("implementers_of: Tallier")
graph_query("writers_to: cast_vote_records") # if graph indexes DB ops
Graph queries answer relational sub-questions without reading source.
Graph-first decomposition (raise η before any windowed read)
The 90/10 deterministic-first rule (I-3) means a relational sub-question should be exhausted on the graph before any Tier-4 read. Codify the verb vocabulary and reach for it first:
| Verb | Answers |
|---|---|
callers_of(sym) / callees_of(sym) |
direct call edges in/out of a symbol |
implementers_of(iface) / subclasses_of(class) |
polymorphic dispatch targets |
writers_to(table) / readers_of(table) |
data-flow endpoints (if graph indexes DB ops) |
importers_of(module) / imported_by(module) |
module-coupling edges |
transitive_callers(sym, depth=N) |
depth-bounded upstream reach (cap the depth — unbounded = a read in disguise) |
callgraph_slice(scope) |
the sub-graph induced by a scope glob — used to partition a surface |
Pushing more Locate work onto these deterministic structural probes is the single biggest lever on search-efficiency η: each is an O(1) index lookup with exact results, where an LLM-authored search is expensive and only probabilistically correct.
Partition derives from the graph, not from a guess. When the surface is
large enough to scatter (skills/scatter/SKILL.md), the per-module fan-out partition
is computed from one parent-side callgraph_slice(scope) — the disjoint
clusters are a structural fact. Do not LLM-guess the clustering; that
re-introduces the inference trap the deterministic-first rule exists to avoid.
Tier 3 — Scoped lexical search
search_text(pattern=r'audit_log\\s*\\.\\s*write', scope='app/flows/**', limit=50)
Caps at 50. If it returns 50, do not raise the cap. Two options:
- Narrow the scope glob.
- Replace the lexical pattern with a Tier 1/2 probe.
Repeated overflow = the question is mis-framed; revise.
Tier 4 — Windowed read
view_file(path='app/flows/vote_casting/record_vote.rb', start=1, end=100)
# if answer is beyond line 100, cursor forward
view_file(path='...', start=100, end=200)
Use windowed reads only after tiers 1–3 have narrowed the target. Reading an entire file is a Phase-T mistake, not a probe.
Tier 5 — Dry-run or fixture inspection
If the mission concerns runtime behavior:
test_dry_run(path='test/flows/record_vote_test.rb', case='when user is guest')
Test files often document intended behavior more cleanly than implementation.
The Operator pattern: scatter subagents
When the mission has ≥2 independent sub-questions, do not pursue them serially in your own context. Spawn subagents.
For a large surface (> 5 modules OR > 25 files) with ≥2 disjoint sub-questions, this scatter is formalized as the TRANCE-gated Scatter-Gather Locate sub-mode — see
skills/scatter/SKILL.mdfor the both-flags activation trigger, the 5-branch fan-out cap, the deterministic graph-derived partition, and the merge+dedup contract. Below the threshold (or for a single / tightly-coupled sub-question), stay serial — the heuristics here apply.
When to scatter
- Sub-questions are topologically disjoint (different modules, different concerns).
- Each sub-question is self-contained enough to answer with a small excerpt of the map.
- Total expected token cost > 15% of remaining budget if pursued serially.
Subagent spec
Each subagent receives:
sub_mission:
parent_mission_id: <MISSION-ID>
question: <natural-language sub-question>
scope: <path globs>
budget:
max_tool_calls: <parent_budget / num_subagents>
max_tokens_input: <parent_budget / num_subagents>
required_finding_count: 1..N
map_excerpt: <only the MAP-MODULES and MAP-GRAPH slice relevant to scope>
Each subagent returns exactly one object:
return:
findings: [FINDING-XXX, ...]
gaps: [...]
telemetry: {tokens_used, tool_calls}
# NO transcript. NO raw tool outputs.
The parent context merges the findings list. Subagent transcripts are
destroyed.
When NOT to scatter
- Sub-question requires tight iteration with another sub-question.
- Only one sub-question exists.
- Budget is already tight; the coordination overhead isn't worth it.
Writing a FINDING
FINDING-017:
claim: "RecordVote#call is the sole writer to cast_vote_records; authorization
is delegated to VotingAuthorizer#authorize_ballot."
evidence:
- path: app/flows/vote_casting/record_vote.rb
lines: 42-78
excerpt_ref: memex://excerpt/7f31ab
- path: app/policies/voting_authorizer.rb
lines: 12-40
excerpt_ref: memex://excerpt/2a9c05
ruled_out:
- "No other CallNode writing to cast_vote_records found in app/** (symbol
probe exhaustive)."
confidence: H
supports_decision: DT-1
Required fields: claim, evidence[], confidence, supports_decision.
ruled_out is first-class. "I searched X and found nothing" is a finding
— often the most valuable one. Do not discard negative results.
Excerpts go to Memex, not into findings.md. The finding carries the reference; the raw text lives in the stable store.
Confidence calibration
| Tier | When |
|---|---|
| H | Claim is directly observed in an AST-derived structural fact or in explicit source text cited verbatim. |
| M | Claim requires a short inferential step over observed evidence (e.g., "this FlowObject likely runs in the request thread because it has no Sidekiq wrapping"). |
| L | Claim is plausible from context but not directly anchored. Flag in GAPS. |
If you catch yourself writing "probably", "seems to", "I believe" — it's not H. Be honest; downstream agents calibrate on your tiers.
Three-strike halt
For each sub-question, maintain a strike counter. A probe returning
confidence: L or empty results = one strike. Three strikes = halt the
sub-question, record it in GAPS with:
GAP-003:
sub_question: "Does the voting FlowObject ever defer to Sidekiq?"
strikes:
- probe: graph_query("callers_of: Sidekiq::Client.push in app/flows/voting/**")
result: empty
- probe: search_text("perform_async|perform_later", scope='app/flows/voting/**')
result: empty
- probe: view_file('app/flows/voting/record_vote.rb', 1, 100)
result: no Sidekiq references; synchronous only
working_hypothesis: "Synchronous in the request thread."
escalate_to: human | follow-up-mission
This is the dead-end guard. Without it, the agent will fixate.
Exit gate
- [ ] Every
DECISION_TARGETsub-question has ≥1 finding at confidence ≥ M, OR is recorded inGAPS. - [ ] Every finding has
path:lineanchors. - [ ] Every finding's
excerpt_refresolves in Memex. - [ ] No finding's claim contains hedging language without an L tier.
- [ ] Tool-call count ≤ 60% of mission budget.
04 同仓库更多 Skills
wine-dxvk-cache-clear
Clear a stale DXVK shader cache that is causing graphical corruption in a Wine or Proton game. Use when: a game shows corrupted textures or shader flicker that started after a driver or DXVK version change.
steam-download-region-fix
Fix a Steam client stuck at very low download speed by changing its download region. Use when: Steam downloads are far below the local internet speed for every game, not just one.
proton-battleye-eac-toggle
Toggle BattlEye or Easy Anti-Cheat runtime support for a Steam Proton game. Use when: a multiplayer game refuses to launch with an anti-cheat error under Proton.
vivi-verify-incoming
Load when reading any upstream artefact handed off to Vivi that carries a sibling .envelope.json. BLOCKING per ECL §6.2.2: the orchestrator MUST have verified the envelope's SHA-256 (eidolons verify-envelope --block / eidolons run --verify) and recorded a verify_pass before dispatch. If no verify_pass exists for the message_id, or a verify_fail is present, REFUSE to process the payload and hand back to the orchestrator. Symmetric receiver gate — every Eidolon enforces it identically.
vivi-parallel-tracks
Load ONLY under TRANCE authorization when the Plan phase yields N independent, non-overlapping implementation tracks (disjoint file sets). Operationalizes the TRANCE G4 form — parallel multi-track implementation in mandatory git-worktree isolation, max 5 clean-context tracks, a per-track verifier cascade, a non-fungible per-track ≤3 reflection budget, explicit stop conditions, and a single-threaded merge/aggregation step. Absent TRANCE gating, Vivi runs exactly as today: single-track A→P→I→V→Δ/R.
vivi-methodology
Full Vivi cycle reference — A(nalyze) → P(lan) → I(mplement) → V(erify) → Δ(Delta)/R(eflect). Use when the task is a non-trivial feature implementation in a brownfield codebase and you need the complete methodology reference: complexity routing, evidence-grounded planning rules, test-anchoring requirements, and failure-escalation thresholds.