AGENT SKILL

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.md for 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_TARGET sub-question has ≥1 finding at confidence ≥ M, OR is recorded in GAPS.
  • [ ] Every finding has path:line anchors.
  • [ ] Every finding's excerpt_ref resolves in Memex.
  • [ ] No finding's claim contains hedging language without an L tier.
  • [ ] Tool-call count ≤ 60% of mission budget.

04 同仓库更多 Skills

Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2