Concepts

Retros as Markdown

The repository is the system of record. A retro is a Markdown file next to the work it is about, so the history of how the team learned is in Git.

What gets written

With the default folders, a retro on 3 October 2026 is team/retros/2026-10-03-retro.md. There is one retro per date. The file’s front matter holds the date, the period, the facilitator, the status (draft, in-progress or complete), the feedback template, the stage, and the objectives the retro focuses on.

The body is ordinary Markdown: a summary, what went well, what did not, insights from the repository, previous action items, the objectives section, new action items, and Insights to share upwards. Sections the extension may rewrite sit between hidden comment markers. If you remove a section’s markers, the extension leaves that section alone.

Feedback lives beside the retro

By default each person has their own file, team/retros/2026-10-03-retro.feedback/<your-name>.md, so two people can write at once without a merge conflict. A shared file, 2026-10-03-retro.feedback.md, is the other mode. The Retros view, Summarise, and Copilot read every feedback file for the retro either way. An entry written when Git has no user.name is stored as Anonymous in the shared file.

You can edit the Markdown by hand. The forms are the supported way to change a retro, an objective, or a feedback entry, so the markers and the front matter stay intact.

The team sees a retro when it is pushed

Prepare checks, read-only, whether the retro’s files are committed and pushed. Until they are, other people cannot pull the retro. The invitation text tells them to pull, open the Retros view, and add feedback. NABS Confidence copies that text. It does not send mail or a chat message.

After a retro is archived

Archiving can remove the retro’s files from the working tree once they are committed and pushed. The record then sits in three places: the GitHub Discussion, the commit that last had the files, and team/retros/archive.json. See Archive to a Discussion.