# Weekly Retro Workflow Implementation Source

## Status

- Date: 2026-05-19
- Source type: discussion-to-implementation-doc
- Status: ready for implementation planning
- Intended next step: create and execute the sibling implementation plan.
- Recommended plan: docs/plans/weekly-retro-workflow/weekly-retro-workflow-plan.md
- Recommended execution state: docs/plans/weekly-retro-workflow/weekly-retro-workflow-execution-state.md

## Purpose

Agent-kit has reporting workflows and a HEURISTIC_SYSTEM retention framework, but
it does not yet have a repo-local engineering retrospective workflow. The desired
feature is an agent-kit version of gstack's `/retro`: generate a weekly
engineering review from commit history and retained workflow records, then
optionally keep local history for trend tracking.

This source document captures the implementation boundary. The goal is to borrow
the useful shape of gstack's retro without copying gstack's preamble, telemetry,
global discovery, hidden home-state defaults, or all-in-one skill architecture.

## Source Material

- Prior user request: evaluate a gstack `/retro` component that reads commit
  history, `timeline.jsonl`, and `learnings.jsonl`, then writes weekly retros for
  trend tracking.
- Retained gstack source:
  `out/projects/graysurf__agent-kit/20260517-142040-gstack-analysis/gstack/retro/SKILL.md`
- Retained gstack user docs:
  `out/projects/graysurf__agent-kit/20260517-142040-gstack-analysis/gstack/docs/skills.md`
- Agent-kit reporting precedent:
  `skills/workflows/reporting/daily-brief/SKILL.md`
- Agent-kit HEURISTIC_SYSTEM framework:
  `HEURISTIC_SYSTEM.md`
- Agent-kit evidence boundary:
  `skills/tools/workflow-evidence/skill-usage/SKILL.md`
- Agent-kit heuristic inbox boundary:
  `skills/workflows/heuristic-system/heuristic-error-inbox/SKILL.md`

## Confirmed Facts

- Gstack `/retro` is a weekly engineering retrospective skill that analyzes
  commit history, work patterns, code quality metrics, persistent history, trend
  tracking, and team-aware contributor breakdowns.
- Gstack loads prior project retros from
  `~/.gstack/projects/{repo_slug}/retros/*.md`, recent timeline events from
  `~/.gstack/projects/{repo_slug}/timeline.jsonl`, and recent learnings from
  `~/.gstack/projects/{repo_slug}/learnings.jsonl`.
- Gstack's raw data pass uses git history commands for commits, numstat, commit
  timestamps, changed files, PR/MR references, author counts, test file counts,
  and optional local histories such as skill usage analytics.
- Gstack computes metrics such as commit type mix, contributors, insertions,
  deletions, test LOC ratio, active days, sessions, hotspots, PR size buckets,
  focus score, ship of the week, streaks, and optional backlog/test health.
- Gstack writes narrative output to the conversation and saves a JSON snapshot
  under `.context/retros/`; global mode writes under `~/.gstack/retros/`.
- Agent-kit already distinguishes workflow skills from deterministic tool
  primitives. Skills own framing and judgment; scripts or CLI primitives own
  deterministic data gathering, validation, redaction, and machine-readable
  output.
- Agent-kit `daily-brief` is the closest reporting precedent: it is a
  user-facing workflow that consumes a lower-level script's JSON output and writes
  durable history only when requested.
- Agent-kit `HEURISTIC_SYSTEM.md` already defines periodic compression:
  repeated retained records should be grouped, compressed, and promoted into
  smaller rules, tests, scripts, primitives, or runbooks.
- Current agent-kit has no tracked `commands/` directory and no native
  `weekly-retro` or `retro` workflow.

## Decisions

- Add the canonical workflow as `weekly-retro`, not `retro`.
- Place it under `skills/workflows/reporting/weekly-retro/`.
- Add a deterministic helper surface owned by the skill:
  `skills/workflows/reporting/weekly-retro/scripts/weekly-retro.sh`.
- Use a Python implementation behind the shell wrapper if needed for reliable
  parsing, for example
  `skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`.
- Make the helper read local repository state by default. Do not fetch from
  remotes unless a future explicit option is added and documented.
- Default output should be stdout. Do not write durable reports unless the user
  supplies an output/history directory or asks the workflow to keep history.
- Use a project-scoped ad hoc run directory from `agent-out project --topic
  weekly-retro --mkdir` when the user wants a one-off saved report but has not
  selected a durable history folder.
- Support optional external JSONL inputs such as `--timeline-jsonl` and
  `--learnings-jsonl`, but do not require gstack files and do not treat them as
  telemetry.
- Use HEURISTIC_SYSTEM records as a first-class agent-kit data source:
  summarize active `heuristic-system/error-inbox/`, archived inbox changes, and
  `heuristic-system/operation-records/` changes during the retro window.
- Keep history schema compact and local:

  ```text
  <history-dir>/
  ├── index.jsonl
  ├── retros/YYYY/YYYY-MM-DD-<repo-slug>-weekly-retro.md
  └── raw/YYYY/YYYY-MM-DD-<repo-slug>-weekly-retro.json
  ```

- Keep `weekly-retro` distinct from `daily-brief`: daily-brief is external
  information synthesis; weekly-retro is repo-local engineering retrospection.

## Scope

- Create a `weekly-retro` workflow skill contract.
- Add deterministic data collection for git commit history, commit type mix,
  changed-file hotspots, author summaries, test-file/test-commit signals, and
  HEURISTIC_SYSTEM record movement.
- Add optional parsing for user-provided `timeline.jsonl` and `learnings.jsonl`
  paths.
- Add optional local history writes with Markdown report, raw JSON, and
  `index.jsonl`.
- Update README/catalog/tooling docs so the workflow is discoverable under
  Reporting.
- Add focused tests for the script contract, parsing, safety boundaries, and docs
  discovery.

## Non-Scope

- Do not add a global `/retro` command, `commands/retro.md`, or a new command
  directory in this slice.
- Do not copy gstack's preamble, gbrain context loading, proactive prompts,
  continuous checkpointing, telemetry, or cross-project global discovery.
- Do not write to `~/.gstack` by default.
- Do not create or update personal memory.
- Do not require remote GitHub/GitLab APIs for the first implementation.
- Do not make retrospective reports part of the normal CI or release gate.
- Do not commit generated weekly retro outputs unless the user explicitly asks
  for a durable tracked report.

## Acceptance Direction

The implemented feature should let a user run a repo-local weekly retro with a
small, inspectable command surface, then let the workflow synthesize the result
into a concise engineering review. A successful first version should answer:

- What shipped this week?
- What changed by commit type and file area?
- Which tests and validation signals moved?
- What happened in `heuristic-system/error-inbox/` and operation records?
- What should be carried into next week's engineering habits or follow-up work?
- Where was history written, if and only if history persistence was requested?

## Open Questions

- None for planning. Implementation can choose the exact JSON field names as long
  as the schema is tested and documented in the skill.
