القائمة
Review completed work and learn. Use when: a task, PR arc, or session is finished and you want to extract learnings, or after ≥5 PRs (the scope checkpoint).
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Dispatch fresh-context refuters (model-agnostic; multi-model opt-in) to attack a completion claim at the shared-trunk pawl before landing. Triggers: pre-land validation, refute.
Dispatch fresh-context refuters (model-agnostic; multi-model opt-in) to attack a completion claim at the shared-trunk pawl before landing. Triggers: pre-land validation, refute.
Run pre mortem.
Stress-test plans before work. Use when: a plan is drafted but not yet executed and you want to surface failure modes, risks, and what would prove it wrong before committing.
Repair skill hygiene. Triggers: "heal-skill", "heal skill", "repair skill hygiene.".
Repair skill hygiene. Triggers: "heal-skill", "heal skill", "repair skill hygiene.".
| name | post-mortem |
| description | Review completed work and learn. Use when: a task, PR arc, or session is finished and you want to extract learnings, or after ≥5 PRs (the scope checkpoint). |
| practices | ["dora-metrics","sre","lean-startup"] |
| hexagonal_role | domain |
| consumes | ["implement","validate","council"] |
| produces | ["result.json"] |
| context_rel | [{"kind":"shared-kernel","with":"standards"}] |
| skill_api_version | 1 |
| metadata | {"tier":"judgment","dependencies":["council","beads-br"]} |
| context | {"window":"fork","intent":{"mode":"task"},"sections":{"exclude":["HISTORY"]},"intel_scope":"full"} |
| output_contract | skills/council/schemas/verdict.json |
Purpose: Wrap up completed work — validate it shipped correctly, extract learnings, process the knowledge backlog, activate high-value insights, and retire stale knowledge.
Runtime note: Hook-driven closeout is runtime-dependent. Claude/OpenCode can wire Phase 2-5 maintenance through lifecycle hooks. Codex CLI v0.115.0+ supports native hooks (same behavior). For older Codex versions without hook surfaces, finish closeout with
ao codex stop.
Move 7 (capture evidence + learning, then ratchet) of the operating loop. Two outputs per loop turn: evidence (test names, snapshot keys, council verdicts, citation events) recorded against the bead and .agents/flywheel/; learnings promoted only under the ratchet rules — noticed once stays in the handoff, repeats twice goes to .agents/learnings/, changes future behavior updates a SKILL.md or template, must-never-regress becomes a gate, core doctrine promotes into PRODUCT.md/GOALS.md/docs/cdlc.md. Most observations die at handoff. That is correct.
Route a promoted learning to the WEAKEST enforcement surface that actually changes behavior — this is the ladder, by strength, not three copies of the same note:
| Surface | Strength | Promote here when |
|---|---|---|
AGENTS.md/CLAUDE.md | always-on context | doctrine relevant to most turns in this repo |
| a SKILL.md | JIT, model-invoked | contextual judgment that fires on a trigger |
| a gate/hook | mechanical, un-skippable | must-never-regress; cannot be left to judgment |
Put it as high as needed and no higher: a hook for what an agent must not be able to skip; a skill for what it should choose well; AGENTS.md for what it should always know. A lesson that only needs to be known doesn't need a hook; a lesson that must never regress is wasted as prose. If the existing hook/gate layer already catches the failure (it fired, just late), the fix is usually one rung weaker — teach a skill/AGENTS.md to run that gate earlier, not add a redundant hook.
Measure the shipped change on real data, not just unit-green. A learning or feature that is unit-correct but has zero observable effect on the real corpus/workload is a STOP signal (stop investing in it), not a "do more" signal. Cite the real-data measurement (counts before/after on the actual corpus), not just "tests pass."
Six phases:
/post-mortem # wraps up recent work
/post-mortem epic-123 # wraps up specific epic
/post-mortem --quick "insight" # quick-capture single learning (no council)
/post-mortem --scope=pr <num> # learn from a merged/rejected PR outcome (absorbed /pr-retro)
/post-mortem --process-only # skip council+extraction, run Phase 3-5 on backlog
/post-mortem --skip-activate # extract + process but don't write MEMORY.md
/post-mortem --deep recent # thorough council review
/post-mortem --mixed epic-123 # cross-vendor (Claude + Codex)
/post-mortem --skip-checkpoint-policy epic-123 # skip ratchet chain validation
Codex CLI v0.115.0+ has native hooks and handles closeout automatically (no extra steps needed). For older Codex versions (hookless fallback), run these after the post-mortem workflow writes learnings and next work:
ao codex stop
ao codex status
ao codex stop uses the latest transcript or history fallback to queue/persist learnings and run close-loop maintenance without runtime hooks.
| Flag | Default | Description |
|---|---|---|
--quick "text" | off | Quick-capture a single learning directly to .agents/learnings/ without running a full post-mortem. Formerly handled by /retro --quick. |
--scope=pr [num] | off | Read a merged/rejected PR outcome as the wrap-up signal instead of a closed bead/epic — mine reviewer feedback into a PR learning. Absorbed the former pr-retro skill. See references/pr-scope.md. |
--process-only | off | Skip council and extraction (Phase 1-2). Run Phase 3-5 on the existing backlog only. |
--skip-activate | off | Extract and process learnings but do not write to MEMORY.md (skip Phase 4 promotions). |
--deep | off | 3 judges (default for post-mortem) |
--mixed | off | Cross-vendor (Claude + Codex) judges |
--explorers=N | off | Each judge spawns N explorers before judging |
--debate | off | Two-round adversarial review |
--skip-checkpoint-policy | off | Skip ratchet chain validation |
--skip-sweep | off | Skip pre-council deep audit sweep |
Read references/quick-mode.md when you need the --quick flag procedure (slug generation, direct learning write, confirmation).
--scope=pr)Read references/pr-scope.md when invoked with --scope=pr. It swaps the bead/epic wrap-up signal for a PR's merge/reject/changes-requested outcome: discover the PR, analyze the outcome, mine reviewer feedback via gh, extract success/failure patterns, and write a dated PR learning to .agents/learnings/. After the PR learning lands, the standard maintenance phases (process → activate → retire → harvest) run as usual. The trigger phrases "PR retro", "learn from this PR", and the legacy pr-retro command all route here.
Read references/execution-steps.md when you need the full Phase 1 procedure: pre-flight checks, reference loading (Step 0.4), checkpoint-policy preflight (0.5), plan/spec loading (Steps 1-2.3), closure integrity audit (2.4), metadata verification (2.5), deep audit sweep (2.6), council invocation (Step 3), and prediction accuracy (3.5).
Before council and retro synthesis, load compiled prevention outputs when they exist:
.agents/planning-rules/*.md.agents/pre-mortem-checks/*.mdUse these compiled artifacts first, then fall back to .agents/findings/registry.jsonl only when compiled outputs are missing or incomplete. Carry matched finding IDs into the retro as Applied findings / Known risks applied context so post-mortem can judge whether the flywheel actually prevented rediscovery.
Read references/phase-2-extract.md when you need the inline learning extraction procedure: gather context (EX.1), classify (EX.2), write learnings (EX.3), test pyramid gap analysis (EX.3.5), scope classification (EX.4), findings registry (EX.5-6).
Before backlog processing, normalize reusable council findings into .agents/findings/registry.jsonl.
Use the tracked contract in docs/contracts/finding-registry.md:
dedup_key, provenance, pattern, detection_question, checklist_item, applicable_when, and confidenceapplicable_when must use the controlled vocabulary from the contractdedup_keyAfter the registry mutation, refresh compiled outputs immediately so the same session can benefit from the updated prevention set.
If hooks/finding-compiler.sh exists, run:
bash hooks/finding-compiler.sh --quiet 2>/dev/null || true
Actionable improvements identified during processing -> append one schema v1.4
batch entry to .agents/rpi/next-work.jsonl using the tracked contract in
../../docs/contracts/next-work.schema.md
and the write procedure in
references/harvest-next-work.md.
Follow the claim/finalize lifecycle documented in references/harvest-next-work.md.
The machine-checkable typed contract is the committed JSON Schema pair
../../schemas/next-work-batch.v1.schema.json
(one JSONL line = one batch entry) and
../../schemas/next-work-item.v1.schema.json
(each items[] element). Validate written rows with
../../scripts/validate-next-work.sh
(--strict to reject malformed output naming the offending field; advisory by
default). The inline bash in references/harvest-next-work.md remains a
dependency-free fallback when the script is unavailable.
mkdir -p .agents/rpi
# Build VALID_ITEMS via the schema-validation flow in references/harvest-next-work.md
# Then append one entry per post-mortem / epic.
# If a harvested item already maps to a known proof surface, preserve it on the
# item as "proof_ref" instead of burying target IDs in free text. Example item:
# [{"title":"Verify the parity gate after proof propagation lands","type":"task","severity":"medium","source":"council-finding","description":"Re-run the targeted validator after the follow-up lands.","target_repo":"agentops","proof_ref":{"kind":"execution_packet","run_id":"6f36a5640805","path":".agents/rpi/runs/6f36a5640805/execution-packet.json"}}]
ENTRY_TIMESTAMP="$(date -Iseconds)"
SOURCE_EPIC="${EPIC_ID:-recent}"
VALID_ITEMS_JSON="${VALID_ITEMS_JSON:-[]}"
printf '%s\n' "$(jq -cn \
--arg source_epic "$SOURCE_EPIC" \
--arg timestamp "$ENTRY_TIMESTAMP" \
--argjson items "$VALID_ITEMS_JSON" \
'{
source_epic: $source_epic,
timestamp: $timestamp,
items: $items,
consumed: false,
claim_status: "available",
claimed_by: null,
claimed_at: null,
consumed_by: null,
consumed_at: null
}'
)" >> .agents/rpi/next-work.jsonl
# Validate the written contract (advisory; add --strict to gate).
bash scripts/validate-next-work.sh .agents/rpi/next-work.jsonl
date -Iseconds > .agents/ao/last-processed
This must be the LAST action in Phase 4.
Phases 3-6 (Maintenance): Read references/maintenance-phases.md for backlog processing, activation, retirement, and harvesting phases. Load when --process-only flag is set or when running full post-mortem.
Read references/user-reporting.md when you need the Step 7 report template, mandatory next-/rpi suggestion format, workflow integration diagram, and example invocations.
Read references/user-reporting.md for full example invocations and what happens in each mode.
| Problem | Cause | Solution |
|---|---|---|
| Council times out | Epic too large or too many files changed | Split post-mortem into smaller reviews or increase timeout |
| No next-work items harvested | Council found no tech debt or improvements | Flywheel stable — write entry with empty items array to next-work.jsonl |
| Checkpoint-policy preflight blocks | Prior FAIL verdict in ratchet chain without fix | Resolve prior failure (fix + re-vibe) or skip checkpoint-policy via --skip-checkpoint-policy |
| Metadata verification fails | Plan vs actual files mismatch or missing cross-references | Include failures in council packet as context.metadata_failures — judges assess severity |
--compound)A comparative-delta mode for projects that run ao goals measure repeatedly
across iterations of the same domain slice. Use when a slice has ≥2 iterations
in the verdict ledger and you want to know: what improved, what regressed, and
what the learning yield was since the last run.
Trigger: run this mode after any ao goals measure where the slice has a
prior iteration record in .agents/goals/verdict-ledger.json.
# Confirm ≥2 iterations exist for a directive in the slice:
jq '[.records[] | select(.record_type=="iteration" and .directive_id=="d-<id>")] | length' \
.agents/goals/verdict-ledger.json
# Run a new iteration (appends one record per directive):
ao goals measure
# Browse iteration history:
ao goals history --goal <directive-id>
Then follow the step-by-step procedure in
references/compound-engineering-retro.md
(Steps CE.0–CE.5): extract N and N-1 records from the ledger, compute the
verdict and satisfaction delta, count learning yield, and write the delta as a
draft learning to .agents/learnings/YYYY-MM-DD-<slice>-iter-delta.md.
The output learning carries status: draft and the run IDs of both iterations;
human or Tier-3 synthesis promotes it to status: reviewed.
Closing the loop with re-steer. When the delta shows a directive failing
chronically, the verdict ledger also drives auto re-steer: ao goals steer recommend prints policy-driven directive mutations from the same ledger, and
ao goals steer apply writes the chosen mutation to GOALS.md — human-gated, via
the non-lossy patcher (policy auto_apply plus explicit confirmation; ADR-0006).
The compound retro names what regressed; re-steer proposes how the directive
should change. See the /goals skill.
skills/council/SKILL.md — Multi-model validation councilskills/validate/SKILL.md — Council validates code (/validate after coding)skills/pre-mortem/SKILL.md — Council validates plans (before implementation)pre-land-refuters — its council artifact (.agents/council/*-pre-land-*.md) is landing evidence this post-mortem consumes--scope=pr): categorize PR feedback, extract success/failure patterns by outcome, write a dated PR learning (soc-qk4b)--scope=pr: PR discovery, outcome analysis, gh feedback mining, PR learning template (absorbed /pr-retro)