Debrief

/debrief — Codex Session Debrief

Publish a structured summary of this session to the central org-memory debrief store:

$OACP_HOME/org-memory/debriefs/<project>/<YYYY>/<MM>/<YYYYMMDD>-<agent>-<session>.md

One session produces exactly one file, written once at session end and never rewritten. The store is the full-fidelity session record; curated outcomes reach other agents through oacp write-event instead (see "Curation guard" below).

Arguments

• /debrief — generate the summary and publish it
• /debrief --dry-run — generate and display the summary without writing anything

Instructions

1. Identify the project

Resolve the project name with this fallback chain:

1. The project_name field in the workspace marker. The marker is gitignored and lives only at the repository's main root, so resolve that root first:

   ROOT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
   python3 -c "import json,sys; print(json.load(open(sys.argv[1]))['project_name'])" "$ROOT/.oacp"
   

2. basename "$ROOT" — not git rev-parse --show-toplevel, which returns the linked-worktree directory when the session is running inside one

3. The working directory basename, when not in a git repo

The name must match the workspace directory under $OACP_HOME/projects/ byte-for-byte — the store path segment is case-sensitive and is validated against that same rule.

2. Collect the session identity

The writer needs five identity values. Gather them before composing the body:

• --project — from step 1
• --agent codex — this runtime's registered project-agent name
• --runtime codex — the runtime family writing the record
• --session — a short stable session id: 1-32 lowercase letters and digits, never hyphens. Use the first 8 characters of the harness session UUID with hyphens stripped when Codex exposes it. Otherwise generate one 8-character lowercase hexadecimal id once for this run and retain it for every retry. This is what distinguishes multiple sessions by the same agent on the same day. If the session keeps working after a debrief has already landed, use the derived continuation id described in step 8 instead.
• --started-utc / --ended-utc — session bounds as ISO 8601 UTC, e.g. 2026-08-25T20:04:11Z. Take these from the clock, never from an estimate; ended_utc must not precede started_utc, and the date of started_utc determines the filename and directory segments.

UTC, not local time. The store path and the <YYYYMMDD> filename prefix are derived from started_utc in UTC. On a machine whose OS timezone is ahead of or behind UTC, a locally-stamped date lands the record in the wrong month directory. Generate both stamps with date -u +%Y-%m-%dT%H:%M:%SZ.

3. Review the session

Gather what actually happened:

• Accomplishments — what was built, fixed, reviewed, or decided
• Decisions — key choices and their rationale
• Issues — tickets created, closed, or updated. If other agents collaborated (parallel runs, review loops), include their closures and PR activity; local git log alone misses them.
• Files changed — git diff --name-only HEAD~5..HEAD 2>/dev/null or git status --short
• Git activity — git log --oneline --since="8 hours ago", in each repo touched for cross-project sessions
• Next actions — carry-forward items, open threads, and blockers that remain live. Before restating a plan, check today's org-memory events and decisions for a ruling that already supersedes it; the published record is immutable.

Your conversation context is the primary source. Git activity supplements it; it does not replace what you remember of the session.

4. Compose the body

Write the body to a scratch file, then hand that file to the writer. The body is everything after the frontmatter — the writer generates the frontmatter itself, so do not write a --- block at the top.

# Session Summary: <project> — YYYY-MM-DD

**Runtime**: codex
**Duration**: <measured wall-clock duration from started_utc to ended_utc>

## What Changed

- bullet points of accomplishments

## Decisions Made

- key decisions with rationale

## Tickets / Issues

- created/closed/updated references (or "None")

## Files Modified

- key files changed

## Next Actions

- [ ] carry-forward items

## Notes

- anything notable (omit the section if nothing)

Use a file-writing tool, never a shell heredoc. Shell expansion corrupts debrief bodies — backticks in a double-quoted heredoc execute as command substitution, and the mangling is silent. Write the body with your runtime's file-writing tool and pass the path.

5. Resolve the shared writer

The catalog has one writer at skills/debrief/scripts/write_debrief.py; the Codex wrapper does not carry a fork. Resolve the writer from the loaded skill directory, never from the current project's working directory.

# Prefer an installed package, where SKILL.md and scripts/ share one directory.
SKILL_DIR="<directory containing the loaded debrief SKILL.md>"

# In a catalog checkout, codex/SKILL.md sits one level below the shared writer.
if [ ! -f "$SKILL_DIR/scripts/write_debrief.py" ] && \
   [ -f "$SKILL_DIR/../scripts/write_debrief.py" ]; then
  SKILL_DIR="$(cd "$SKILL_DIR/.." && pwd)"
fi

# Try the common project and global Codex install locations.
if [ ! -f "$SKILL_DIR/scripts/write_debrief.py" ]; then
  for d in "$PWD/.agents/skills/debrief" \
           "${CODEX_HOME:-$HOME/.codex}/skills/debrief"; do
    [ -f "$d/scripts/write_debrief.py" ] && SKILL_DIR="$d" && break
  done
fi

test -f "$SKILL_DIR/scripts/write_debrief.py" \
  || { echo "debrief writer not found; re-install the skill" >&2; exit 1; }

Stop here if the writer cannot be resolved. Do not hand-compose a record into the store — the frontmatter, the content hash, and the publication primitive are the writer's contract, and a hand-written file satisfies none of them.

6. Dry run

/debrief --dry-run stops here. Run the step 7 command with --dry-run appended: the writer validates the identity and body, composes the exact record it would publish, prints it, and touches nothing — no directories created, no files written. Status is reported as dry-run.

Show the composed record and the target path, then stop. Do not continue to step 7, and do not report the session as debriefed.

7. Publish

python3 "$SKILL_DIR/scripts/write_debrief.py" \
  --project "<project>" \
  --agent codex \
  --runtime codex \
  --session "<session>" \
  --started-utc "<started>" \
  --ended-utc "<ended>" \
  --body-file "<path-to-body>" \
  --json

The writer validates the schema, computes the content hash, stages the record privately, publishes it with an atomic no-replace link, and reads it back to confirm. Exit codes: 0 published (or an idempotent re-publish of a byte-identical record), 1 validation error, 2 publication failure.

Publication is failure-atomic — the canonical path only ever holds a complete, verified record. On any failure the path stays absent; at worst a private .stage.* file remains, and a later successful publication of the same record sweeps it. The writer only ever publishes an inode it created itself, so a .stage.* file that appears from anywhere else is never adopted — oacp doctor reports it and it is safe to delete by hand.

8. Handle a collision

--session collisions are the one failure that needs a judgment call:

• Byte-identical record already published → reported as idempotent. Nothing to do; the run already landed.
• Different record at the same path → hard failure. A published debrief is never replaced. Re-publish under a new session identifier; the existing record stays as it is.

Corrections and follow-ups are new artifacts too — a later debrief, or an event referencing the original — never an edit to a landed file.

A session that keeps working after its own debrief. Publish a continuation segment under the same project, agent, and runtime: suffix the session id with the segment number (b31ffdea → b31ffdea2, then b31ffdea3), set started_utc to the previous record's ended_utc, and set ended_utc to now. The suffixed form stays inside the 1-32 lowercase alphanumeric grammar. Open the body by naming the parent record and the span it covers; never backfill the landed record or skip the continuation.

9. Confirm

Print the canonical path, the status, and the content hash from the writer's JSON output.

Curation guard

Raw debriefs never enter recent.md or events/. Only curated folds do. If the session produced an outcome other agents or projects need, write it as a separate event:

oacp write-event --type decision --project "<project>" --agent codex ...

Set the event's source_ref to the debrief filename stem (<YYYYMMDD>-<agent>-<session>) so the two can be reconciled later.

Notes

• Keep it concise — 2-6 bullets per section. If the session was trivial, say so rather than padding.
• Facts over narrative: the store is read by curation tooling, not for prose.
• Debrief files are never auto-loaded at session start; they are permanent history, not context.
• The store does not have to exist first — the writer provisions its own tree. oacp org-memory init is a convenience, never a precondition.
• oacp doctor validates store setup — layout, staging artifacts, symlinks. It never opens debrief files; schema and hash correctness are the writer's contract, verified at publication.