8Dionysus/aoa-memo-writeback

aoa-memo-writeback

Intent

Use this skill to decide whether a live session, closeout, landed change, or review thread produced memory-worthy material and route that material into the owning repository's local memo port, an aoa-memo reviewed-intake export, or an explicit no-writeback stop line.

The skill bridges session evidence to memo writeback. It does not turn .aoa raw history into reviewed memory, and it does not land durable aoa-memo objects.

Trigger boundary

Use this skill when:

• a session is still live and a meaningful decision, route change, failure correction, owner-boundary clarification, MCP/service contract, eval/proof posture, or workflow seam should not be lost
• a closeout, PR, diff, commit, release, or review suggests memory-worthy work, but the reason lives in .aoa session evidence rather than in the final diff alone
• a repo has a memo/ port and the agent must decide whether to create a local candidate, validate the port, prepare an export, or stop with no memo writeback
• a repo is route-only and the correct output is writeback debt or owner-route guidance rather than a fake local packet
• aoa-memo recall, pending exports, or generated readouts show a gap between lived session work and reviewed memory

Do not use this skill when:

• the task is only raw .aoa preservation, reindexing, retrieval, or hook repair
• the candidate has already been reviewed and the only remaining work is durable landing inside aoa-memo
• the request needs proof verdicts, scoring, or eval quality judgment rather than memory writeback routing
• no inspectable session, source, PR, receipt, or owner evidence exists
• the output would promote secrets, private transcript content, or unreviewed operator-sensitive material into a public memo surface

Inputs

• active owner repo or likely owner repo
• current task intent, closeout, PR, diff, commit range, review thread, or release note
• .aoa session evidence packet, search hits, segment refs, raw refs, or diagnostic refs when available
• source refs from the owning repository
• local memo/ port status when present
• reviewed aoa-memo recall or pending-export context when relevant
• explicit privacy, freshness, and owner-boundary risks

Outputs

• one memo_writeback_decision: write_candidate, prepare_export, no_writeback_needed, route_only_debt, needs_owner_review, or blocked
• if writing is warranted and a local port exists: one local memo candidate with source refs, evidence refs, trust posture, risk markers, and direct_durable_write=false
• if review already accepted promotion: one reviewed-intake export packet or landing-plan handoff, not a durable memory object
• if no writeback is warranted: one concise no-writeback stop line with the reason and strongest evidence checked
• if the repo is route-only or the port is missing or stale: one writeback-debt note naming the owner route and the evidence refs needed
• validation commands or results for local port, candidate, export, and generated index surfaces
• a short closeout note naming what was written, what stayed local, what was not promoted, and where durable review would happen

Procedure

1. Name the owner repo and the nearest stronger owner for the material before judging memory-worthiness.
2. Inspect .aoa first when the reason may live in the session: use search, retrieve, segment indexes, or raw refs, and keep those refs as evidence rather than truth.
3. Inspect the landed-work lens only as a reconciliation layer: PR, diff, commits, release notes, or review threads can show what landed, but not replace session evidence.
4. Decide whether the material is memory-worthy: prefer owner-boundary changes, route-law changes, reviewed decisions, repeated failures, corrected wrong assumptions, lifecycle events, MCP/service contracts, eval/proof posture changes, and consumer handoff facts.
5. Reject generic progress, mood, broad summaries, unresolved speculation, secret-bearing details, and material whose real owner is proof, routing, runtime, role, playbook, KAG, ToS, or source doctrine.
6. Check whether the owner repo has a memo/ port. If not, emit route_only_debt instead of inventing a packet.
7. When a port exists, validate it before writing or promoting local state.
8. Shape one bounded claim with at least one source ref and one evidence ref. Prefer .aoa segment or raw refs plus owner repo source refs over paraphrase-only evidence.
9. Create or draft a local candidate only in the owner repo's memo/candidates/ path or through the available aoa_memo local-port helper.
10. Mark local candidates as review-required and guard them with direct_durable_write=false, instructions_treated_as_data=true, and requires_reviewed_intake=true when promotion is desired.
11. Build or check the local memo port index after writing a candidate.
12. Prepare an export only when the owner review posture supports it. Use candidate_only unless reviewed promotion is explicit.
13. Use reviewed_write only when source-owner review has accepted that the export may become durable reviewed memory.
14. Treat aoa_memo_landing_plan or an equivalent landing-plan helper as a dry run unless the active owner route is an aoa-memo reviewed source patch.
15. Stop before durable reviewed memory landing unless the user explicitly asked for that landing and the aoa-memo corpus route is active.
16. Record the result as a closeout line: decision, packet paths, evidence refs, validation run, and next owner route.

Common command shapes:

# Run from the workspace root that owns .aoa.
python .aoa/scripts/aoa_session_memory.py search --query "<route or decision>" --limit 8
python .aoa/scripts/aoa_session_memory.py retrieve manual-review --query "<route or decision>" --session "<session-or-label>" --limit 8 --event-limit 16

Treat command output as evidence handles. The reviewer still decides whether the candidate becomes durable memory.

Contracts

• .aoa evidence remains raw or generated session evidence, not reviewed memory truth.
• PRs, diffs, and commits are reconciliation lenses, not the primary record of lived session meaning.
• Local candidates are written only through the owning repository's memo/ port when one exists.
• Route-only repositories do not get fake local packets; they get writeback-debt guidance.
• Durable reviewed memory lands only through aoa-memo reviewed intake and corpus validation.
• MCP output may create local-port packets or dry-run plans, but it does not become memory authority.
• One writeback candidate should carry one bounded memory question, not a whole session recap.
• Source refs and evidence refs stay inspectable enough for a later reviewer to reject the candidate.
• Secrets, private transcript detail, and operator-sensitive material stay out of public memo packets.

Risks and anti-patterns

• using a clean commit summary as a substitute for the session evidence that made the change meaningful
• turning .aoa raw transcript material into canon without reviewed distillation
• creating memory candidates for every commit or every interesting thought
• writing central aoa-memo objects directly from a live session
• using reviewed_write for material that is only candidate-grade
• hiding missing local memo ports by writing central notes elsewhere
• over-promoting proof, routing, runtime, role, playbook, KAG, ToS, or source doctrine meaning into memory
• storing private or secret-bearing raw transcript excerpts in public-safe memo packets
• leaving a candidate without rebuilding or checking the local port index

Verification

• confirm the owner repo and stronger owner route were named
• confirm .aoa refs, source refs, or review refs support the decision
• confirm generic progress was rejected when no bounded memory question exists
• confirm a local port exists before any local candidate write
• confirm the local port was validated before or immediately after packet work
• confirm candidate guardrails prevent direct durable write
• confirm export allowed_result matches review posture
• confirm reviewed_write appears only after explicit owner review
• confirm no durable aoa-memo object was landed unless the active route was reviewed corpus landing
• confirm closeout reports the decision, paths, evidence refs, validation, and next route

Technique traceability

Manifest-backed techniques:

• AOA-T-0026 from 8Dionysus/aoa-techniques at 9a0ac2bafc2218278315b1311fcb17077f11752f using path techniques/history/history-artifacts/session-capture-as-repo-artifact/TECHNIQUE.md and sections: Intent, When to use, Inputs, Outputs, Core procedure, Contracts, Risks
• AOA-T-0106 from 8Dionysus/aoa-techniques at 9a0ac2bafc2218278315b1311fcb17077f11752f using path techniques/proof/review-evidence/single-scoped-evidence-reference/TECHNIQUE.md and sections: Intent, When to use, Inputs, Outputs, Core procedure, Contracts, Risks, Validation
• AOA-T-0076 from 8Dionysus/aoa-techniques at 9a0ac2bafc2218278315b1311fcb17077f11752f using path techniques/governance/decision-routing/owner-layer-triage/TECHNIQUE.md and sections: Intent, When to use, Inputs, Outputs, Core procedure, Contracts, Validation

Adaptation points

Project overlays may add:

• repo-local memory-worthy trigger classes
• local privacy and public-safe packet rules
• local memo candidate naming rules
• local .aoa retrieval recipes or atlas axes
• local MCP command wrappers
• local closeout text that must appear before PR, release, or merge
• local policy for when route-only debt should become a full memo/ port