aoa-decision

Intent

Use this skill as the front door for AoA docs/decisions/ work. It decides whether the task is to find, create, or correct a decision record, uses the workspace decision graph as the first lookup path when available, and keeps the owning repository's decision files and validators as source truth.

Trigger boundary

Use this skill when:

• the task mentions docs/decisions/, decision records, ADRs, decision indexes, decision graph, or decision-lane symmetry
• the user asks which prior decision, source surface, owner boundary, status, supersession, or rationale applies
• a new durable decision record may be needed after a structural, workflow, tooling, source/export, or authority change
• an existing decision note, index metadata, supersession, source-surface list, or generated decision index may need correction
• the work spans more than one AoA repository and graph lookup can reduce context load

Do not use this skill when:

• the task is a normal docs edit with no durable decision-lane implication
• the real question is only source-of-truth ambiguity; use aoa-source-of-truth-check
• the real question is only whether a decision should be recorded; use aoa-adr-write
• the request is only to summarize code, tests, or release notes without decision rationale
• a repo-local route card forbids changing decision surfaces in the current scope

Inputs

• user intent, target repository, touched paths, or decision ID when known
• available aoa_decisions MCP tools or a local graph builder fallback,

including status, issues, changed-path, source-surface, owner-surface, and repo-symmetry packets

• repo-local docs/decisions/AGENTS.md, README.md, TEMPLATE.md, generated indexes, and nearest existing records
• source surfaces that the decision record explains
• validation commands from the owning repository

Outputs

• one chosen route: aoa-decision-find, aoa-decision-create, or aoa-decision-correct
• compact graph or source context used for the route decision
• explicit owner repository and source-truth surface
• validation path for any write or correction
• stop line when the graph is stale, missing, or not authoritative enough

Procedure

1. classify the task:

• find or understand: use aoa-decision-find
• create or record a new rationale: use aoa-decision-create
• correct, supersede, reindex, or repair metadata: use aoa-decision-correct

1. use the aoa_decisions MCP first when it is available; request status and

the smallest relevant packet before broad file reads:

• graph health and blockers: aoa_decisions_status and

aoa_decisions_issues

• touched path: aoa_decisions_changed_path
• source surface: aoa_decisions_source_surface
• owner surface: aoa_decisions_owner_surface
• repo comparison: aoa_decisions_repo_symmetry
• decision ID or known record: aoa_decisions_decision
• repo slice when the target repo is known: aoa_decisions_repo

1. use aoa_decisions_search only after the status/issues and the relevant

changed-path, source-surface, owner-surface, repo, or decision packet is missing, stale, or too narrow; split a long natural-language request into smaller anchors before broad search

1. if MCP is unavailable, locate abyss-stack in the current workspace or a

known local checkout, then run its graph builder, such as python <abyss-stack>/scripts/build_workspace_decision_graph.py --check --json

1. if graph lookup is unavailable too, use repo-local rg and generated

decision indexes, then read the source decision notes directly

1. load only the chosen subskill; do not load find, create, and correct

instructions at the same time

1. before any write, read the target repo's decision route card and template;

if issue_count > 0, inspect aoa_decisions_issues and do not write in a repo whose decision lane has unresolved graph issues

1. after any write, run the repo-local decision-index generator/check and then

refresh or check the workspace graph and decision-graph lane when available

1. report the source decision file, graph freshness posture, validation run, and

any remaining owner-route risk

Contracts

• the graph accelerates lookup; it does not own decision truth
• source files in the owning repository remain stronger than MCP packets,

generated graph nodes, and generated indexes

• the router chooses one subskill to control cost and avoid conflicting advice
• cross-repo symmetry must be appropriate to the target repo, not forced from a

sibling template

• no MCP write tool may create, accept, or correct a decision record silently
• stale graph findings must be refreshed or downgraded before they shape a write
• graph issues block writes in the affected repo and downgrade cross-repo

confidence elsewhere until reported

Risks and anti-patterns

• treating the workspace graph as an authority instead of a read model
• loading every subskill for a simple lookup
• starting with broad graph search when a changed path, owner surface, source

surface, repo, or decision ID can produce a smaller packet

• creating a decision note when a lighter source-of-truth or change summary is enough
• copying a sibling decision structure without checking the local owner surface
• updating generated indexes without the source decision note, or vice versa
• failing to refresh the workspace graph after changing decision files

Verification

• confirm exactly one route was selected
• confirm aoa_decisions was used first when available, or the fallback was named
• confirm graph issue posture was checked before create/correct routes
• confirm broad aoa_decisions_search was skipped when a narrower packet was

sufficient, or explain why it was needed

• confirm the owning repository and source decision surface are explicit
• confirm any write uses repo-local route law and validators
• confirm generated indexes and the workspace graph are not treated as source truth
• confirm the final report names validation and any skipped check

Technique traceability

Manifest-backed techniques:

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

Adaptation points

• stable MCP server name for the current environment
• repo-local decision ID prefix and template
• repo-local decision-index generator and validation commands
• workspace graph output path or fallback builder command
• local stop line for repositories that intentionally do not carry decisions