aoa-decision-create

Intent

Use this skill when a real structural, workflow, tooling, source/export, or authority decision needs a durable repo-local docs/decisions/ note and the workspace graph should help find the right placement, neighbors, and ID context.

Trigger boundary

Use this skill when:

• a change creates durable rationale that future agents need before repeating the route
• the owner repository already has or intentionally needs a docs/decisions/ lane
• graph lookup should identify similar prior decisions, next ID, source surfaces, or symmetry constraints
• a decision note must be created alongside code, docs, MCP, skill, validator, or generated-index changes

Do not use this skill when:

• no decision has been made yet and the work is still option framing
• the change is self-evident and a commit or change summary is enough
• the target repository has no appropriate decision lane and the task does not explicitly add one
• an existing record can be corrected instead; use aoa-decision-correct
• the decision would copy another repo's rationale without local owner evidence

Inputs

• chosen decision and the options that shaped it
• target repository and source surfaces changed by the decision
• graph status, issue packet, changed-path/source-surface/owner-surface packet,

or search results for related records

• repo-local decision route card, README, template, generated indexes, and latest records
• repo-local decision-index and validation commands

Outputs

• one new source decision note with canonical ID, status, date, owner surface, index metadata, context, options, decision, rationale, consequences, source surfaces, and follow-up route
• refreshed repo-local generated decision indexes
• refreshed or checked workspace decision graph
• validation summary and any remaining owner-route risk

Procedure

1. confirm a real decision exists and is worth preserving
2. use aoa_decisions status and issues first; if the target repo has graph

issues, stop and route to correction before creating a new record

1. use changed-path, source-surface, owner-surface, repo, and decision packets

to collect related records and repo decision-lane context

1. use broad search only when the narrower packets do not identify enough

placement context; split long free-text intent into path, repo, surface, or decision anchors first

1. read the target repo's docs/decisions/AGENTS.md, README.md, TEMPLATE.md,

generated index shape, and latest decision records

1. choose the next canonical ID from source files, not from memory alone
2. write the note in the target repo's established format and metadata language
3. name only the source surfaces this decision actually explains
4. keep graph, generated indexes, tests, and runtime evidence as context rather

than decision authority

1. run the repo-local decision-index generator, then the check form and any

affected surface validator

1. refresh or check the workspace graph and run the decision-graph lane when available
2. report the new decision path, graph freshness, and validation

Contracts

• a decision note records why; it does not replace the active source surface
• next ID selection must be verified from source files
• sibling decisions may inform shape, but the target repo owns its own rationale
• generated indexes must be rebuilt from source metadata, not hand-edited as truth
• workspace graph refresh is part of done after creating a record
• unresolved graph issues in the target repo block creation until corrected

Risks and anti-patterns

• creating process noise for trivial changes
• writing a decision before the choice is actually made
• copying a sibling record and leaving mismatched owner surfaces
• omitting rejected options or consequences when they shaped the choice
• using broad graph search before available path, repo, or surface packets
• forgetting generated indexes or workspace graph refresh
• using MCP output as if it created or accepted the decision
• creating a new note while unknown decision-lane surfaces are already present

Verification

• confirm the new record has canonical ID, status, date, owner surface, and index metadata
• confirm source surfaces match the actual diff
• confirm repo-local decision indexes were regenerated and checked
• confirm graph issue posture was checked before writing
• confirm broad search was needed, or skipped because narrower packets were sufficient
• confirm affected validators were run or explicitly skipped with reason
• confirm workspace graph refresh/check and decision-graph lane see the new record

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

• repository-specific ID prefix and numbering
• decision template fields and index metadata vocabulary
• validation commands and generated index builder path
• graph refresh command or MCP refresh tool