# Plan: Weekly Retro Workflow

## Overview

Add a repo-local `weekly-retro` reporting workflow that turns git history and
HEURISTIC_SYSTEM record movement into an engineering retrospective. The workflow
borrows gstack's useful retro shape, but keeps agent-kit boundaries: no telemetry,
no gstack home-state dependency, no proactive preamble, and deterministic data
collection in a small script. The skill will own user-facing judgment and
synthesis, while the helper script owns parseable git/record summaries and
optional local history output.

## Read First

- Primary source: `docs/plans/weekly-retro-workflow/weekly-retro-workflow-discussion-source.md`
- Source type: `discussion-to-implementation-doc`
- Open questions carried into execution: none

## Scope

- In scope: `weekly-retro` workflow skill, deterministic script wrapper and
  parser, repo-local git metrics, HEURISTIC_SYSTEM record summaries, optional
  JSONL inputs, optional local history writes, catalog/tooling docs, and focused
  tests.
- Out of scope: gstack preamble or telemetry, `commands/retro.md`, global
  cross-repo discovery, default writes to `~/.gstack`, remote provider API
  integration, CI/release gating, and generated retro reports committed by
  default.

## Assumptions

1. The canonical agent-kit name is `weekly-retro`; `retro` can remain a future
   alias only if a command surface is introduced later.
2. The first implementation should run from a git work tree and use local git
   history by default. It should not call `git fetch` unless a later explicit
   option is added.
3. A shell wrapper may delegate to Python for parsing. This matches existing
   agent-kit helper patterns and keeps JSON handling out of ad hoc shell parsing.
4. The workflow should be useful without any `timeline.jsonl` or
   `learnings.jsonl`; those files are optional inputs, not required runtime
   state.
5. Local history writes are opt-in and path-explicit. Ad hoc saved output can use
   `agent-out project --topic weekly-retro --mkdir`.

## Sprint 1: Workflow Contract And Data Model

**Goal**: Establish `weekly-retro` as the canonical reporting workflow and define
the deterministic data contract before adding broader integration.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k weekly_retro`,
  `scripts/check.sh --docs`, `scripts/check.sh --markdown`
- Verify: the skill contract and helper schema are discoverable, script help is
  stable, and no generated report is written by default.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 1.1: Add the weekly-retro workflow skill

- **Location**:
  - `skills/workflows/reporting/weekly-retro/SKILL.md`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Create the workflow contract. Define when to use
  `weekly-retro`, how it relates to `daily-brief`, how it consumes the helper's
  JSON output, when history may be written, and which gstack behaviors are
  intentionally excluded.
- **Dependencies**:
  - none
- **Complexity**: 3
- **Acceptance criteria**:
  - Skill frontmatter validates through the repo skill contract checks.
  - The skill is categorized as a Reporting workflow.
  - The skill states that it reads local repo state and optional explicit JSONL
    inputs, not telemetry.
  - The skill forbids default writes to `~/.gstack`, memory, or tracked reports.
  - The skill points agents at `agent-out project --topic weekly-retro --mkdir`
    for ad hoc saved artifacts.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
  - `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh`

### Task 1.2: Define the helper command surface and JSON schema

- **Location**:
  - `skills/workflows/reporting/weekly-retro/scripts/weekly-retro.sh`
  - `skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Add a small deterministic helper with stable help text,
  argument parsing, and schema output. Implement the shell wrapper as the only
  public script entrypoint and put nontrivial parsing in Python.
- **Dependencies**:
  - Task 1.1
- **Complexity**: 4
- **Acceptance criteria**:
  - `weekly-retro.sh --help` documents defaults, window syntax, output formats,
    optional JSONL paths, and opt-in history writes.
  - Default invocation writes no files and prints a machine-readable
    `weekly-retro.report.v1` JSON envelope.
  - Supported windows include default current week, `--since YYYY-MM-DD`,
    `--days N`, and explicit `--from YYYY-MM-DD --to YYYY-MM-DD`.
  - Invalid windows fail closed with a usage error and no writes.
  - The schema includes repo identity, window metadata, git summary,
    commit-type buckets, author summaries, file hotspots, test signals,
    heuristic-system summary, optional input summaries, warnings, and source
    commands.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`

### Task 1.3: Add script contract regression coverage

- **Location**:
  - `tests/script_specs/skills/workflows/reporting/weekly-retro/scripts/weekly-retro.sh.json`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Add script spec coverage and focused tests for command help,
  default no-write behavior, JSON schema shape, and usage failures.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 2
- **Acceptance criteria**:
  - Script spec resolves the wrapper from the skill path.
  - Tests fail if the helper loses `--format json`, `--history-dir`, or
    optional JSONL arguments.
  - Tests verify default execution does not create a history directory.
- **Validation**:
  - `scripts/check.sh --tests -- -k weekly_retro`
  - `scripts/check.sh --contracts`

## Sprint 2: Repo Signals And Report History

**Goal**: Implement the useful retro signals from local repo data and optional
agent-kit history inputs.
**Demo/Validation**:

- Command(s): `scripts/check.sh --tests -- -k weekly_retro`,
  `scripts/check.sh --docs`
- Verify: the helper can summarize git commits and HEURISTIC_SYSTEM movement
  from fixtures and from the current repository without remote APIs.

**PR grouping intent**: group
**Execution Profile**: serial

### Task 2.1: Implement git history collection and classification

- **Location**:
  - `skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Collect local git data for the selected window and classify
  engineering activity into stable buckets.
- **Dependencies**:
  - Task 1.2
- **Complexity**: 5
- **Acceptance criteria**:
  - The helper runs only local git commands by default and records those commands
    in the JSON `sources` section.
  - Conventional commit prefixes are classified at least as `feat`, `fix`,
    `refactor`, `test`, `docs`, `chore`, `ci`, `release`, and `other`.
  - File hotspots include top changed files and top-level area buckets.
  - Author summaries include commit counts and changed-line totals when numstat
    data is available.
  - Test signals include changed test files, test-related commit count, and test
    LOC ratio when computable.
  - Empty windows produce a valid report with a warning instead of a traceback.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`

### Task 2.2: Summarize HEURISTIC_SYSTEM record movement

- **Location**:
  - `skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
  - `HEURISTIC_SYSTEM.md`
- **Description**: Treat retained workflow records as a first-class retro source.
  Summarize active inbox status, archived inbox changes, and operation-record
  changes during the selected window.
- **Dependencies**:
  - Task 2.1
- **Complexity**: 4
- **Acceptance criteria**:
  - The helper reports active inbox counts by lifecycle status and severity when
    `heuristic-system/error-inbox/` exists.
  - It reports entries added, modified, archived, or removed during the selected
    window using git history over `heuristic-system/error-inbox/`.
  - It reports operation-record changes under
    `heuristic-system/operation-records/`.
  - Missing HEURISTIC_SYSTEM directories are handled as `not_present`, not as
    hard failures.
  - Docs explain that `weekly-retro` summarizes retained records but does not
    create, mutate, or archive inbox entries.
- **Validation**:
  - `scripts/check.sh --tests -- -k 'weekly_retro or heuristic_system'`
  - `scripts/check.sh --docs`

### Task 2.3: Support optional JSONL inputs without adopting telemetry

- **Location**:
  - `skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`
  - `skills/workflows/reporting/weekly-retro/SKILL.md`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Add optional `--timeline-jsonl` and `--learnings-jsonl`
  inputs. Parse only explicit paths supplied by the caller and summarize counts,
  recent entries, and parse warnings.
- **Dependencies**:
  - Task 1.2
  - Task 2.1
  - Task 2.2
- **Complexity**: 3
- **Acceptance criteria**:
  - The helper never searches home directories for JSONL inputs by default.
  - Missing optional JSONL paths fail with a clear usage/runtime error.
  - Malformed JSONL lines are counted and reported without aborting the whole
    report unless every line is unusable.
  - The workflow docs state that these inputs are optional evidence, not
    telemetry.
- **Validation**:
  - `scripts/check.sh --tests -- -k weekly_retro`

### Task 2.4: Add opt-in report history writes and comparison

- **Location**:
  - `skills/workflows/reporting/weekly-retro/bin/weekly_retro.py`
  - `skills/workflows/reporting/weekly-retro/SKILL.md`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Let users preserve retros in an explicit local history
  directory. Write raw JSON, rendered Markdown, and an append-only index when
  requested, then compare against the latest prior report in the same history
  folder.
- **Dependencies**:
  - Task 2.1
  - Task 2.2
  - Task 2.3
- **Complexity**: 4
- **Acceptance criteria**:
  - History writes require `--history-dir <dir> --write`; `--history-dir` without
    `--write` reports the intended path but does not write.
  - Markdown reports are written under
    `retros/YYYY/YYYY-MM-DD-<repo-slug>-weekly-retro.md`.
  - Raw JSON reports are written under
    `raw/YYYY/YYYY-MM-DD-<repo-slug>-weekly-retro.json`.
  - `index.jsonl` records relative paths, repo slug, generated timestamp, window,
    commit count, test signal summary, heuristic-system summary, and warnings.
  - Prior report comparison is best-effort and explicitly absent on first run.
  - No generated reports are tracked unless the user explicitly chooses a tracked
    directory.
- **Validation**:
  - `scripts/check.sh --tests -- -k weekly_retro`

## Sprint 3: Catalog Integration And Maintenance Gates

**Goal**: Make `weekly-retro` discoverable as an agent-kit reporting workflow and
validate the plan with normal repo gates.
**Demo/Validation**:

- Command(s): `scripts/check.sh --all`
- Verify: catalogs, docs, contracts, and targeted tests agree on the workflow
  boundary.

**PR grouping intent**: group
**Execution Profile**: parallel-x2

### Task 3.1: Update reporting catalogs and tooling docs

- **Location**:
  - `README.md`
  - `skills/README.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `skills/workflows/reporting/weekly-retro/SKILL.md`
- **Description**: Add `weekly-retro` to the public workflow catalog and tooling
  index. Document the helper command, output schema, and relationship to
  `daily-brief`, `skill-usage`, and `heuristic-error-inbox`.
- **Dependencies**:
  - Task 1.1
  - Task 1.2
  - Task 2.2
- **Complexity**: 3
- **Acceptance criteria**:
  - README lists `weekly-retro` under Reporting workflows.
  - Tooling index names the helper script and its deterministic boundary.
  - Docs distinguish `weekly-retro` from `daily-brief`.
  - Docs state that `weekly-retro` reads HEURISTIC_SYSTEM records but does not
    mutate them.
- **Validation**:
  - `scripts/check.sh --docs`
  - `scripts/check.sh --markdown`

### Task 3.2: Add a lightweight fixture-backed smoke path

- **Location**:
  - `skills/workflows/reporting/weekly-retro/tests/fixtures/git-history.log`
  - `skills/workflows/reporting/weekly-retro/tests/fixtures/heuristic-system-history.log`
  - `skills/workflows/reporting/weekly-retro/tests/fixtures/timeline.jsonl`
  - `skills/workflows/reporting/weekly-retro/tests/fixtures/learnings.jsonl`
  - `skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`
- **Description**: Add fixtures that exercise git-log parsing, heuristic-system
  record movement, optional JSONL parsing, and history writes without requiring
  network access or external CLIs.
- **Dependencies**:
  - Task 2.1
  - Task 2.2
  - Task 2.3
  - Task 2.4
- **Complexity**: 3
- **Acceptance criteria**:
  - Tests can run in CI without `gh`, `glab`, gstack, gbrain, or network access.
  - Fixture outputs assert stable schema fields rather than brittle prose.
  - The smoke path covers both no-history and opt-in history modes.
- **Validation**:
  - `scripts/check.sh --tests -- skills/workflows/reporting/weekly-retro/tests/test_workflows_reporting_weekly_retro.py`

### Task 3.3: Run final validation and record residual limits

- **Location**:
  - `skills/workflows/reporting/weekly-retro/SKILL.md`
  - `docs/runbooks/skills/TOOLING_INDEX_V2.md`
  - `docs/plans/weekly-retro-workflow/weekly-retro-workflow-execution-state.md`
- **Description**: Run targeted and full validation, then record known limits in
  the execution state if implementation proceeds from this plan.
- **Dependencies**:
  - Task 3.1
  - Task 3.2
- **Complexity**: 2
- **Acceptance criteria**:
  - Targeted weekly-retro tests pass.
  - Docs and markdown checks pass.
  - `scripts/check.sh --all` passes or any blocker is recorded with exact command
    output and follow-up.
  - Execution state, when created during implementation, records validation
    commands and residual out-of-scope items such as global retros and remote PR
    API enrichment.
- **Validation**:
  - `scripts/check.sh --tests -- -k weekly_retro`
  - `scripts/check.sh --docs`
  - `scripts/check.sh --markdown`
  - `scripts/check.sh --all`

## Testing Strategy

- Unit: parser tests for window handling, conventional commit classification,
  numstat parsing, file hotspot aggregation, heuristic-system status extraction,
  optional JSONL parsing, and history path generation.
- Integration: temporary git-repo fixtures that create commits across several
  prefixes and paths, then run `weekly-retro.sh --format json`.
- Script contract: script spec and help tests for the wrapper path and supported
  options.
- Docs: catalog, tooling index, and skill contract checks.
- Manual smoke: run the helper in `/Users/terry/.config/agent-kit` with a recent
  window and no history writes, inspect the JSON/Markdown summary, then run an
  opt-in history write to a temporary `agent-out` directory.

## Risks & gotchas

- Git history shape varies across merge commits, squash merges, no remote, and
  shallow clones. The first version should prefer local `HEAD` history and avoid
  remote API claims.
- Parsing git output in shell is brittle. Keep parsing in Python and keep the
  shell wrapper thin.
- Retros can become noisy if every metric is treated as equally important. The
  workflow should lead with shipped themes, fix/test balance, and
  heuristic-system movement, then keep lower-value metrics in tables.
- Optional JSONL inputs may contain malformed partial lines. Count and report
  parse warnings instead of treating them as trusted complete evidence.
- Generated retros can become durable clutter. Default to stdout and require an
  explicit history directory for writes.
- HEURISTIC_SYSTEM summaries must not replace the `heuristic-error-inbox`
  lifecycle workflow. `weekly-retro` is read-only over those records.

## Rollback plan

- Remove `skills/workflows/reporting/weekly-retro/` and its tests.
- Remove weekly-retro entries from `README.md`, `skills/README.md`, and
  `docs/runbooks/skills/TOOLING_INDEX_V2.md`.
- Remove the script spec under
  `tests/script_specs/skills/workflows/reporting/weekly-retro/`.
- Delete any opt-in generated report directory created during validation if it
  lives under `out/` or another temporary path.
