gilde

← All craftbooks

Engineering Retrospective

Ship and releaseevalv2.0.8released 2026-09-05

Build a data-grounded engineering retrospective from git history: activity, hotspots, review patterns, and per-person growth notes for a given window.

Steps

Entry step: scope-retro. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Define the retrospective window and evidence contractengineering operations analystentry

    Lock the period, repositories, participants, questions, identity aliases, and privacy boundaries.

    Show working prompt
    Confirm the requested time window, repository scope, comparison baseline, participants, timezone, team events, and intended audience. Resolve obvious author aliases from read-only history and label ambiguous identities instead of merging them. Define the questions the retrospective should answer, the datasets required, exclusions, privacy rules, and known blind spots such as squash merges or off-platform reviews.

Observable handoff: write the completed result to `retro/scope.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
  2. Collect and reconcile the engineering evidenceengineering data analyst

    Gather reproducible activity, churn, hotspot, collaboration, and quality signals with caveats.

    Show working prompt
    Collect the evidence contract defined in `retro/scope.md`. When `run_git` is available in your function schema, use its read-only log, show, and diff subcommands; do not use shell pipelines. Otherwise, inventory and read the authoritative repository exports or workspace records named in the scope, and explicitly record that live history is unavailable. Preserve the exact query arguments or source paths and result counts. Reconcile totals across authors and date boundaries, sample the work behind the numbers, and identify hotspots, change concentration, review or pairing signals visible in the evidence, rework, test activity, documentation, maintenance, and operational work. Compare with the chosen baseline where possible. Treat missing data as missing, not zero, and never invent unavailable repository or review metrics.

Observable handoff: write the completed result to `retro/evidence.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
  3. Write the engineering retrospectiveengineering manager

    Turn the evidence into balanced lessons, growth notes, and owned experiments.

    Show working prompt
    Write a retrospective grounded in `retro/evidence.md`. Explain the period's goals and events before interpreting metrics. Highlight outcomes, strengths, bottlenecks, hotspots, recurring rework, review patterns, maintenance load, and changes from baseline, citing paths or examples. Include constructive per-person growth notes only when supported by multiple observations; name contributions and opportunities without ranking people or equating volume with value. End with three to five owned, measurable experiments and a date for checking results.

Observable handoff: write the completed result to `retro/engineering-retrospective.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
  4. Evaluate the deliverableengineering leadership reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `retro/engineering-retrospective.md`, `retro/scope.md`, `retro/evidence.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.

1. The time window, repository scope, baseline, identities, and evidence queries are reproducible.
2. Counts reconcile or discrepancies are explained, and missing signals are not treated as zero.
3. Every important conclusion traces to multiple observations, paths, or examples rather than activity volume alone.
4. Strengths, friction, hotspots, maintenance, collaboration, and changes from baseline are balanced and contextualized.
5. Individual notes are evidence-backed, constructive, privacy-conscious, and never framed as rankings or performance scores.
6. Experiments have owners, measurable outcomes, and a review date.

Open `retro/engineering-retrospective.md`, `retro/scope.md`, `retro/evidence.md` with `read_file`. Write the evidence-backed review to `reviews/engineering-retrospective-review.md` in the artifacts drawer with `write_artifact`. Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. Then use `advance_task_step` for the active task: PASS routes to `finish`; REVISE routes to `repair` for review rounds 1 through 2, and the 3th REVISE routes to `needs-user`. Never route to finish while a criterion is unmet.
  5. Repair the deliverableengineering manager

    Fix only the concrete gaps from the latest independent review.

    Show working prompt
    Read `reviews/engineering-retrospective-review.md` with `read_artifact` and repair every failed criterion in `retro/engineering-retrospective.md`, `retro/scope.md`, `retro/evidence.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `retro/engineering-retrospective.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
  6. Finishproject lead

    All deterministic and reviewer criteria passed.

    Show working prompt
    The independent review passed. Read `reviews/engineering-retrospective-review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`retro/engineering-retrospective.md`, `retro/scope.md`, `retro/evidence.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  7. Escalate unresolved concernsproject lead

    The bounded repair loop ended without a defensible pass.

    Show working prompt
    The deliverable did not pass after 3 review rounds. Do not claim success. Read `reviews/engineering-retrospective-review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license