Project Retrospectives

OAT project retrospectives capture how an implementation run went and route what should change next. The workflow uses two skills:

• oat-project-retro generates {PROJECT_PATH}/references/project-retro.md and applies approved repo improvements.
• oat-project-retro-file files tracker-bound feedback into repository or upstream GitHub issues and OAT backlog items.

A configured retro post-approval sequence step can generate the artifact after final feedback exists and before project completion freezes lifecycle artifacts. Interactive completion also offers generation when the artifact is missing. Neither path applies or files findings without separate consent.

Generate a retrospective

Ask to run the project retro, or configure retro in workflow.postImplementSequence.postApproval. Generate mode resolves the active project, inventories evidence, renders the retro artifact, and records the run in the project log when that log exists.

Evidence is read in this order:

1. project-log.md
2. oat-execution-learnings.md, when present
3. Lifecycle artifacts such as implementation.md, state.md, plan.md, design and discovery artifacts, reviews, and evidence ledgers
4. The current session or run transcript when the environment makes it available

The artifact identifies every used or unavailable source. Missing transcript access is recorded rather than hidden, and runtime claims fall back to durable ledgers when transcript output is incomplete. Findings distinguish confirmed causes, hypotheses, and inconclusive mechanisms.

Evidence status remains used | unavailable. When an evidence family is partial, split it into truthful source entries, such as archived-review-markdown: unavailable and gate-receipts: used, rather than recording review-artifacts: unavailable. Do not add a partial evidence status. Derivative current-run reconnaissance transcripts are not original project-run evidence.

Scale depth to the evidence

Keep output concise by default. Every section must add distinct information. Prefer references to evidence over repeated chronology. For a small project, keep core sections brief. Use subsections and tables only for evidence-rich projects where they improve decisions. The required core and register contracts stay intact; evidence volume controls depth, not a new configuration or consent setting.

Each material incident remains understandable without opening another artifact. Use stable evidence anchors such as project-log event IDs, artifact headings, review paths, decision IDs, and commit IDs. Anchors supplement but never replace explanation.

Narrative sections have distinct ownership:

• Challenges and Struggles owns the complete incident narrative: what happened, impact, response, and result.
• Where We Changed Course records only the trigger, changed direction, and outcome.
• Domain Learnings abstracts reusable lessons without replaying chronology.
• Gotchas for Humans and Gotchas for Autonomous Agents contain future-facing instructions rather than incident summaries.

Every retro contains two machine-scannable registers:

• Repo Improvements (RP-NN) route each item through Disposition: apply for a bounded repo edit or Disposition: file for a tracker follow-up.
• OAT Upstream Feedback (UP-NN) contains sanitized, tracker-ready suggestions for toolkit improvements. The section remains present with an explicit empty state when no upstream item is warranted.

Per-item statuses and frontmatter rollups make interrupted and repeated runs resumable. The promotions rollup covers RP apply-items; the filing rollup covers UP items plus RP file-items.

Project-log receipt

When a project log exists, generate mode appends this one-line structural receipt:

retro artifact=<path> evidence_used=<csv> evidence_unavailable=<csv> promotions=<number> upstream=<number> apply=<performed|declined|skipped|deferred> filing=<performed|declined|skipped|deferred>

Source identifiers are validated, deduplicated, sorted bytewise ascending, and joined with commas and no spaces; an empty source list is none. Counts describe the generated registers.

Before any apply decision or filing dispatch, capture one immutable eligibility snapshot for that action. Apply snapshots contain unsettled RP apply-items; filing snapshots contain the lane-tagged union of unsettled UP items and RP file-items. Do not recompute initial eligibility after an action changes the registers.

Derive each outcome from that snapshot with this precedence:

1. An initially empty snapshot is skipped.
2. An action-level interactive rejection before entry is declined.
3. Non-entry, failure, or any snapshot member still unsettled is deferred.
4. An entered action that completes normally with no snapshot member remaining is performed.

This makes an all-settled successful action performed, even though its post-action eligible set is empty. For mixed filing lanes, any initially eligible lane left unsettled by absent or none routing makes the single filing outcome deferred; normal completion that settles every initial lane is performed.

The append uses stable structural identity and the exact rendered body:

oat project log append --project "$PROJECT_PATH" --structural \
  --producer oat-project-retro \
  --ref project-retro \
  --body "$RECEIPT_BODY"

Apply repo improvements

Invoke apply mode directly with wording such as "apply the retro findings." Apply mode requires an existing retro and never regenerates it. It processes only RP items whose authoritative disposition is apply and whose status is proposed or approved.

Interactive runs present each item, target, rationale, and concrete edit before approval. Non-interactive runs apply items only when workflow.retro.apply: auto; an absent value or ask leaves proposals untouched when no interaction is possible.

Application follows the item type:

• documentation updates the canonical existing page;
• agent instructions update the narrowest existing instruction surface;
• rules update the canonical scoped rule;
• decisions use oat decision new after an exact duplicate check; and
• code follow-ups default to Disposition: file and remain outside apply mode.

After a successful application, the skill records Status: applied and an Applied-ref. Re-runs skip settled items and recover an exact prior side effect instead of applying it twice.

For a docs item whose safely normalized target canonical path has the exact, case-sensitive final component project-log.md, apply mode uses oat project log append and never directly edits the log. Absolute paths, traversal, and ambiguous normalization fail closed; suffixes and prefixed lookalikes remain ordinary docs targets.

The proposal must identify the prior heading or event being corrected and preserve the original entry. The appended judgment uses --type feedback, --scope project, --area "retro correction $RP_ID", and a body whose stable identity includes both the RP ID and original-entry anchor. Before appending, perform semantic post-side-effect recovery. The skill recovers an exact uncommitted or committed correction and stops on partial, divergent, or multiple matches before it appends.

The correction is committed first without retro writeback. A later retro-only writeback records Status: applied and an Applied-ref naming the full correction commit plus exact generated heading. Applied-ref is considered recorded only after the correction and retro writeback are durably committed. Append failure creates neither commit; correction-commit failure leaves the RP unsettled for exact recovery; writeback failure preserves the correction commit and retries only the writeback. This remains a bounded docs special case; it adds no RP type and does not weaken the normal docs apply contract.

File tracker feedback

Run oat-project-retro-file against the active project's retro or an explicit artifact path. It extracts every UP item and each RP item with Disposition: file; it never mutates apply-items.

Before item approval, the skill reports a lane-by-destination capability matrix:

Interactive runs confirm or override configured lane defaults and choose a disposition for each suspected duplicate:

1. Strengthen the existing issue or backlog item with new evidence.
2. File as new despite the candidate.
3. Skip without filing.
4. Link existing without adding content.

Strengthening is the default when applicable, but it is still an external write. Non-interactive configuration does not authorize modifying an existing destination; an unambiguous duplicate may be linked without an external write, while ambiguous candidates remain unsettled for interactive review.

Local receipts and reruns

Before skipping an already-filed item, the filing skill runs a pre-selection integrity pass. A local backlog destination is complete only when its path exists, its current contents still represent the retro proposal, its full Destination-receipt names the latest exact-path commit containing that path, and Remote-visibility is pushed or unpushed. A valid exact recovery may retain filed without mutating the destination. A missing or invalid local receipt that cannot be recovered cannot remain filed.

New and strengthened local destinations use destination-first ordering: commit the destination mutation alone, verify that commit contains the backlog path and excludes retro writeback, then record its receipt in a later retro writeback commit. A failed destination commit never produces filed. A local link performs no destination mutation, but must recover and validate the latest exact-path commit before it can be filed.

Remote visibility is independent of local durability. No configured upstream means unpushed; the skill never pushes without separate authorization. GitHub destinations use a validated issue URL and explicitly leave Destination-receipt and Remote-visibility as —.

Public destinations receive a sanitization check when the source repository is private. Filing records the confirmed URL or backlog path in Destination and updates the filing rollup. Unavailable lanes and missing backlog metadata are reported rather than silently rerouted or invented.

Configure non-interactive consent

The workflow.retro namespace controls non-interactive actions:

Explicit auto or filing destinations count as consent only for their bounded action. Architecture, security, product-scope, credential, destructive, and duplicate-mutation boundaries still require direction. See Configuration for the full key reference.

Summary versus retrospective

Use the summary to preserve the delivered system and its decisions. Use the retro to preserve execution lessons, course changes, repo improvements, and upstream toolkit feedback.