8Dionysus/aoa-decision-create

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
• the parent has classified a create route, but the chosen decision, target repository, source surfaces, graph status, or repo-local decision law is unavailable inside the active evidence boundary; select this child only to stop with blocked_missing_input rather than invent creation context

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. if the create route is selected but the chosen decision, target repository, source surfaces, graph status, or repo-local decision law is unavailable inside the active evidence boundary and no permitted packet or source read can supply it, stop with blocked_missing_input; do not relabel missing input as deferred_owner_boundary
2. confirm a real decision exists and is worth preserving
3. use aoa_decisions status and issues first; if the target repo has graph issues, stop and route to correction before creating a new record
4. use changed-path, source-surface, owner-surface, repo, and decision packets to collect related records and repo decision-lane context
5. 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
6. read the target repo's docs/decisions/AGENTS.md, README.md, TEMPLATE.md, generated index shape, and latest decision records
7. choose the next canonical ID from source files, not from memory alone
8. write the note in the target repo's established format and metadata language
9. name only the source surfaces this decision actually explains
10. keep graph, generated indexes, tests, and runtime evidence as context rather than decision authority
11. run the repo-local decision-index generator, then the check form and any affected surface validator
12. refresh or check the workspace graph and run the decision-graph lane when available
13. 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
• missing required creation context inside the active evidence boundary ends as blocked_missing_input, not as an owner-boundary deferral

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
• relabelling absent creation inputs as deferred_owner_boundary

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 absent creation inputs stopped as blocked_missing_input without being relabelled as deferred_owner_boundary
• 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