8Dionysus/aoa-decision-find

aoa-decision-find

Intent

Use this skill to find decision rationale quickly across AoA repositories while keeping final claims grounded in the owning repository's authored decision note.

Trigger boundary

Use this skill when:

• the user asks what decision exists, which record explains a route, or why a boundary was chosen
• a task needs relevant prior decision context before editing code, docs, validation, MCP, skill, or repo topology
• a cross-repo comparison needs decision IDs, owner surfaces, source surfaces, statuses, or supersession links
• graph search can prevent broad manual reads across many decision lanes
• no graph status, changed paths, target records, or owner repository packet is available inside the active evidence boundary, and no permitted graph or fallback index can supply them; select this route only to stop with blocked_missing_input rather than invent lookup results

Do not use this skill when:

• a new decision note must be written; use aoa-decision-create
• an existing note or metadata must be edited; use aoa-decision-correct
• the task is only source-of-truth mapping outside decision records
• the user needs a final architectural decision that has not been made yet
• the graph or indexes are enough for lookup but the answer would require source-note verification and no source read is possible

Inputs

• query terms, touched paths, target repository, decision ID, source surface, or owner surface
• aoa_decisions MCP search, packet, changed-path, source-surface, owner-surface, repo-symmetry, issue, repo, decision, or summary tools when available
• fallback generated graph files or repo-local decision indexes
• source decision notes for final verification

Outputs

• ranked decision matches with repo, decision ID, path, status, and reason for relevance
• source-note refs used for any claim
• note when graph data is stale, missing, or only a candidate hint
• next route if creation or correction is needed

Procedure

1. query aoa_decisions first when available; choose the narrowest packet: changed-path for touched files, source-surface for cited inputs, owner-surface for ownership routes, repo for a known target repository, and decision for a known ID
2. check status or issues; if issue_count > 0, report the graph issue posture and treat graph matches as candidates until source notes are inspected
3. use broad graph search only when no changed path, source surface, owner surface, repo, or decision ID can narrow the route, or after those packets fail to produce a sufficient candidate; split long free-text intent into smaller anchors before searching
4. if MCP is unavailable, use the latest workspace graph output or repo-local generated indexes as a search aid
5. when no graph status, changed paths, target records, or owner repository packet is available inside the active evidence boundary, and no permitted graph or fallback index can supply them, stop with blocked_missing_input; do not relabel missing input as deferred_owner_boundary
6. read the source decision note before making a rationale, authority, or supersession claim
7. compare source-surface lists and owner metadata against the user's target paths when judging relevance
8. distinguish exact matches, likely matches, weak analogies, and missing records
9. if no adequate record exists, route to aoa-decision-create; if a record is stale or wrong, route to aoa-decision-correct
10. return compact evidence: decision ID, source path, key reason, and remaining uncertainty

Contracts

• MCP packets and graph nodes are hints until checked against source notes
• source-note claims must cite the repo and decision path
• related sibling decisions are examples, not templates to copy blindly
• missing evidence should be reported as missing, not filled with doctrine
• missing graph and owner inputs inside the permitted evidence boundary end as blocked_missing_input, not as an owner-boundary deferral
• avoid loading unrelated decision lanes after a sufficient match is found
• graph issues reduce confidence; they do not authorize guessing

Risks and anti-patterns

• over-answering from generated graph fields without opening the source record
• using broad graph search before available path, repo, surface, or decision anchors
• treating a title match as semantic equivalence
• ignoring supersession or status fields
• turning a weak sibling analogy into a target-repo rule
• searching every repo when a repo or path already narrows the route

Verification

• confirm graph or fallback lookup path was used
• confirm changed-path/source/owner packet was used when the input made one available
• confirm broad search was needed, or skipped because a narrower packet was sufficient
• confirm final claims came from source notes, not only generated graph data
• confirm match confidence and any uncertainty are visible
• confirm absent graph and owner inputs stopped as blocked_missing_input without being relabelled as deferred_owner_boundary
• confirm missing or stale records route to create or correct instead of being hidden
• confirm the answer stays compact enough for the current task

Technique traceability

Manifest-backed techniques:

• AOA-T-0002 from 8Dionysus/aoa-techniques at cd276f040d55d490bd015b8698c7a5d594b9f875 using path techniques/instruction/docs-boundary/source-of-truth-layout/TECHNIQUE.md and sections: Intent, When to use, Inputs, Outputs, Core procedure, Contracts, Risks, Validation

Adaptation points

• MCP server and tool names
• workspace graph cache path
• repo-local index filenames and source-note metadata fields
• source reference format expected by the active chat surface