Retro Analysis

Retro Analysis

Run a factual engineering retrospective over a defined time window. The purpose is to explain what changed, how the work happened, what quality signals say, what was learned, and what should improve next. This is an analysis workflow, not a performance-ranking or blame exercise.

Use it manually at the end of a day, week, sprint, or release; on a recurring schedule; or when asked what was shipped, where time went, or how delivery quality is trending. When a specific implementation has just reached its goal, run this analysis before or alongside olko:wrap-up so the delivery audit and the broader retrospective remain distinct.

Invocation

Accept one of these arguments:

• no argument or 7d: the previous seven calendar days
• 24h: the previous 24 hours
• 14d or 30d: the previous N calendar days
• compare or compare 14d: compare the selected window with the immediately preceding window of equal length
• global, global 14d: aggregate across discoverable repositories and agent sessions

If the argument is invalid, print the accepted forms and stop. Do not silently choose a different window.

Calendar windows are aligned to midnight in the operator's local timezone. A short hourly window may use a relative timestamp. State the resolved start, end, timezone, scope, and comparison window at the beginning of the report.

Step 0, before collecting any evidence: resolve the durable context store by invoking the context-repo skill. If it returns BLOCKED or LOCAL_ONLY, continue local-only and label the limitation in the report. Resolving a store does not authorize writing a snapshot to it. This retro must never fail because the store is unavailable.

Safety and evidence rules

• Be read-only by default in the analyzed repository. The named exceptions are a context-repo bootstrap performed under that skill's own consent flow, and one context-store snapshot commit and push when the user explicitly consented to remote snapshot persistence for this run or through a recorded standing workflow preference. Outside those exceptions, this skill never pushes, merges, deploys, closes issues, edits source, or rewrites history in the analyzed repository.
• A retro may write one task-owned snapshot per run. Generate one collision-resistant run id and reuse it for the whole run, in the form <YYYYMMDDTHHMMSSZ>-<short-unique-suffix>. Derive one scope key: the normalized <owner>-<repo> slug in repository mode and the literal global in global mode, independent of which repositories were discovered or their order. The filename is <run-id>-<scope-key>-<window>.md. Write it to the context store's retro/ only with explicit remote-persistence consent; otherwise use .context/retros/ when that directory exists or local persistence was explicitly requested. Create the file only if absent and generate a new run id on collision; never overwrite an existing snapshot.
• Do not fetch or refresh remote refs unless the user or the surrounding workflow authorized that read-side state change. If refs may be stale, say so and use the available evidence.
• Preserve dirty work, untracked files, existing snapshots, credentials, and unrelated temporary artifacts.
• Never infer delivery from a local commit. Treat local Git, remote/PR state, CI, deployment, and device or human QA as separate evidence gates.
• Do not expose secrets, tokens, private prompts, or raw session content. Use aggregate counts and redacted references only.
• Missing data is UNKNOWN, not zero. Distinguish “none found” from “not available”.
• Do not turn commit count, lines changed, hours, or AI-assisted activity into a simplistic productivity score. Use them as context for the narrative.

1. Establish scope and baseline

For repository mode:

1. Identify the repository, current branch, HEAD, configured author, base branch, and working-tree state.
2. Preserve and report pre-existing dirty paths; do not include their changes as delivered work unless the evidence links them to the window.
3. Use the repository's local timezone for calendar boundaries. Use UTC timestamps in stored machine-readable data.
4. Read only relevant project documentation and task artifacts needed to interpret the changes. Do not invent milestones, objectives, or acceptance criteria.
5. Locate prior snapshots by the same scope key and window, newest run timestamp first: the context store's retro/, then its legacy retros/, then .context/retros/. For pre-run-id repository snapshots, fall back to matching the repository slug; never treat a repository snapshot as a global snapshot. Reading the store first is what makes compare and global work across machines instead of only where the last run happened. Load the immediately preceding comparable snapshot when available.

For global mode:

1. Discover repositories from the configured workspace locations or an existing discovery tool. If discovery is unavailable, report that limitation and continue with explicitly supplied paths.
2. For each repository, collect the same bounded evidence as repository mode and skip missing, inaccessible, or non-Git directories.
3. Optionally include available agent/session summaries or tool telemetry, but only as aggregate, redacted evidence. Do not require a specific agent vendor, plugin, or telemetry format.
4. Keep per-project results separate before producing cross-project totals. Never hide a repository-level failure in an aggregate.
5. Use the literal global scope key to locate the prior global snapshot with the same store-first ordering as repository mode. Never derive the lookup key from the discovered repository set or its order.

2. Collect raw evidence

Capture enough raw data to reproduce the analysis. Prefer stable Git/provider CLIs already present in the environment. Save only the normalized snapshot unless raw artifacts were explicitly requested.

Repository history

Collect, bounded to the resolved window and scope:

• commit hash, author, timestamp, subject, body, and parent information
• insertions, deletions, files changed, and test-file versus production-file changes
• commit type signals from Conventional Commit prefixes, labels, or equivalent repository conventions
• pull request or merge request references present in commits, and provider state when a provider CLI is available
• changed-file frequency, churn, and hotspots; distinguish generated, vendored, lockfile, and source files when possible
• per-author commit and file ownership signals, including co-authors and AI-assisted markers only when explicitly present

Use git log --shortstat or equivalent for commit-level change counts and git diff --numstat or equivalent for test/source proportions. If a command cannot run, record the command and reason; do not substitute invented values.

Delivery and quality signals

Inspect only signals that exist in the repository or authorized provider tooling:

• branch and remote tracking state, current PR title/body, review state, and current-head checks
• test files, test commands, recent test-related commits, and known failing or skipped checks
• changelog, release notes, issue/task references, and plan artifacts when present
• TODO/backlog markers when a project-maintained backlog exists
• regression fixes, reverted changes, follow-up fixes, and repeated failure patterns
• optional review or static-analysis summaries, clearly labeling unavailable or rate-limited providers

Never call an absent test suite “healthy”; report NOT_AVAILABLE. Never call a skipped check green.

Work-pattern signals

When timestamps are available:

• build an hour-of-day histogram in local time
• group commits or activity into sessions separated by at least 45 minutes of inactivity
• classify sessions as deep (3+ hours), medium (1–3 hours), or micro (<1 hour)
• count active days, longest streak, and context switches between repositories or work areas

Treat commit timestamps as a proxy, not proof of keyboard time. If session telemetry exists, prefer it and name the source.

3. Compute the analysis

Use the evidence to calculate, or explicitly mark unavailable, the following dimensions:

Shipping and scope

• features, fixes, refactors, docs, tests, chores, and releases shipped
• commits, weighted commits, active days, contributors, and referenced PRs
• version range or release identifiers when the repository exposes them
• logical lines changed and raw lines changed, reported separately
• plan or objective items completed, deferred, or still open when a plan is available

Quality and maintainability

• test lines or test files changed relative to production changes
• test commands run and their current result
• regressions, reverts, repeated fixes, and hotspots with high churn
• type, lint, build, security, review, and release signals when available
• backlog/TODO health only when there is a maintained source to inspect

Do not reward large diffs or penalize small ones without explaining their context. A small change that closes a high-value objective can be the most important shipment.

Focus and delivery flow

• commit-type mix and fix ratio; flag a high fix ratio as a signal for investigation, not a diagnosis
• PR/MR size buckets and time-to-merge when provider data is available
• work sessions, time-of-day distribution, context switching, and focus patterns
• planned versus unplanned work, if the plan and change evidence support the comparison
• the single most consequential shipment or decision, with evidence and caveats

People and collaboration

For multi-author work, provide a factual per-author view of commits, change volume, areas touched, review or PR participation, and notable contributions. Include a team view of ownership concentration, cross-review, handoffs, and shared hotspots. Avoid ranking people by raw LOC or commit count.

Use the configured Git author as the personal focus only when it is unambiguous. Otherwise produce a team report and state that no personal identity was selected.

4. Compare and track trends

For compare or any window with a prior snapshot:

• compare features/fixes, commits, active days, contributors, PRs, change volume, test signals, regressions, and backlog movement
• identify meaningful directional changes and explain whether the evidence is strong, weak, or incomplete
• preserve the same metric definitions between periods; do not compare a repository window to a global window as if they were equivalent
• report streaks, recurring hotspots, repeated failure modes, and unresolved improvements only when snapshots support them

Store a JSON snapshot with stable keys, the run id, UTC timestamps, resolved window, scope key, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. When the store pointer resolved and the user explicitly consented to remote snapshot persistence for this run or through a recorded standing workflow preference, create <clone>/retro/<run-id>-<scope-key>-<window>.md, with the machine-comparable JSON in a fenced block inside that file rather than as a separate sidecar, then commit and push per the context-repo caller contract, lease and validator included. Store resolution alone never authorizes the write, commit, or push. Without that consent, or when the store is unavailable, fall back to .context/retros/ exactly as described above and do not modify the store. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.

5. Optionally promote durable lessons

This phase is opt-in. A retrospective remains read-only unless the user or the surrounding workflow explicitly requests promotion to the shared ledger. Do not silently turn analysis into a write operation.

Before adding any finding:

1. Locate and read the current shared ledger. When a Git-backed repository ledger exists, read that repository file directly and treat it as authoritative. If it is absent or inaccessible, report NOT_AVAILABLE and do not claim that the ledger was checked.
2. Classify the finding as one of:
   • local action: a project- or task-specific follow-up that belongs in the report or backlog, not the shared ledger.
   • lesson: a durable practice that generalizes across projects.
   • trap: a non-obvious failure mode that can silently produce incorrect work.
   • preference: a stable way the operator wants agents to work.
3. Promote only non-obvious, durable, cross-project lessons, traps, or preferences. Keep local actions in the retrospective or project task system.
4. Attach evidence to every promoted finding: a source path, commit, check, or other redacted reference, or the concrete failure that caused the rule. Do not promote an unsupported impression.
5. Do not duplicate existing project instructions, shared-ledger notes, or behavior already enforced by an automated check. A thin ledger is more useful than a repetitive one.

When promotion is authorized, append new notes using the current ledger schema; never rewrite, reorder, or overwrite existing entries. If no note is justified, append nothing. Report each added note ID, or NOT_WRITTEN when no note was added, promotion was not requested, or the ledger could not be safely updated.

6. Produce the report

Lead with a concise, shareable summary of the period. Then use this order:

1. Scope and evidence: window, timezone, repositories, branch/base, sources, and limitations.
2. Summary table: shipping, activity, quality, and delivery metrics with UNKNOWN where needed.
3. What shipped: the most important features, fixes, releases, or decisions, tied to commits/PRs.
4. Trends: comparison with the previous period, if available.
5. Time and sessions: active days, session shape, time distribution, and context switching.
6. Quality and test health: checks, regressions, churn hotspots, review signals, and open risks.
7. Plan completion: objective items completed, deferred, or missing evidence.
8. Focus and collaboration: personal or team analysis with fair context.
9. Top wins: three evidence-backed wins when enough evidence exists.
10. Improvements: three concrete, small, actionable improvements; fewer is fine when evidence is limited.
11. Next-period habits: explicit habits or experiments with an owner or trigger when known.
12. Limitations: missing refs, unavailable provider data, stale telemetry, dirty work, or ambiguous attribution.

Use compact tables for exact metrics and prose for interpretation. Label inference as inference. Link or name evidence paths/commit IDs where useful, but never paste private content.

7. End-of-task handoff

If this run is explicitly closing a completed implementation, continue with olko:wrap-up:

• use the retro to check that the delivered work matches the original idea and to capture follow-up items
• let wrap-up perform the separate local/remote/PR/CI/deployment/QA gates and task-owned cleanup
• preserve the retro snapshot and report any limitation instead of deleting evidence

For a periodic or global retrospective, do not clean worktrees, branches, logs, or temporary files unless the user explicitly asks for that separate cleanup. Analysis alone must not alter delivery state.

Minimal final status

End every run with:

RETRO_STATUS: DONE | DONE_WITH_LIMITATIONS | BLOCKED
WINDOW: <resolved window and timezone>
SCOPE: <repository or repositories>
SNAPSHOT: <path, NOT_WRITTEN, or NOT_AVAILABLE>
STORE: <owner/name@sha> | LOCAL_ONLY | NOT_AVAILABLE
TOP_FINDINGS: <short summary>
NEXT_ACTIONS: <short actionable list>

Use BLOCKED only when the requested scope cannot be analyzed safely or the required evidence is inaccessible. A partial but clearly labeled report is DONE_WITH_LIMITATIONS.