retrospective-evidence
Skill174 starsChanged 2 months agoMITView on GitHub
Where to find objective evidence about a completed cycle - work protocol, workflow state, git history and CI.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-runtimeSkill
- arc42-documentationSkill
- authoring-rolesSkill
- context-packSkill
- create-agent-skillSkill
- create-pr-azdoSkill
- create-pr-githubSkill
- detect-diagram-crossingsSkill
- flowchart_layout_optimizerSkill
- generate-demo-artifactsSkill
- generate-release-screenshotsSkill
- git-rebase-mainSkill
- merge-conflict-resolutionSkill
- next-issue-numberSkill
- pre-pr-checklistSkill
- retrospective-evidenceSkill
- run-dotnet-testsSkill
- run-uatSkill
- run-workflowSkill
- update-test-snapshotsSkill
- update-workflow-diagramSkill
- view-pr-githubSkill
- watch-uat-azdo-prSkill
- watch-uat-github-prSkill
- website-accessibility-checkSkill
- website-create-examplesSkill
- website-devtoolsSkill
- website-quality-checkSkill
- website-visual-assetsSkill
- agent-runtimeSkill
- arc42-documentationSkill
- authoring-rolesSkill
- context-packSkill
- create-agent-skillSkill
- create-pr-azdoSkill
- create-pr-githubSkill
- detect-diagram-crossingsSkill
- flowchart_layout_optimizerSkill
- generate-demo-artifactsSkill
- generate-release-screenshotsSkill
- git-rebase-mainSkill
- merge-conflict-resolutionSkill
- next-issue-numberSkill
- pre-pr-checklistSkill
- run-dotnet-testsSkill
- run-uatSkill
- run-workflowSkill
- update-test-snapshotsSkill
- update-workflow-diagramSkill
- view-pr-githubSkill
- watch-uat-azdo-prSkill
- watch-uat-github-prSkill
- website-accessibility-checkSkill
- website-create-examplesSkill
- website-devtoolsSkill
- website-quality-checkSkill
- website-visual-assetsSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Look at *why* it repeated: an unclear specification usually shows up as repeated Developer rework, not as a Requirements Engineer problem.
- Distinctive: line 35
Start with the retained work item's Release Manager entry to identify the merged PR and published release.
- Very specific: line 47
Do not use origin/main..HEAD for a post-release documentation follow-up.
- Distinctive: line 71
Every improvement opportunity needs three things or it is a wish:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Retrospective Evidence
A retrospective is only as good as what it can point at. This is where the objective record lives.
The highest-signal source is state.json
jq '{attempts, open_questions, gates}' docs/<type>/NNN-<slug>/state.jsonattempts— a stage that ran three times is a workflow defect, not bad luck. Look at why it repeated: an unclear specification usually shows up as repeated Developer rework, not as a Requirements Engineer problem.open_questions— a question nobody answered means a role proceeded on an assumption. If the assumption turned out wrong, that is a finding about the gate design, not about the role.gates— a gate that was never contested when it should have been, or one that fired on something trivial, is a rule worth adjusting.
The work protocol
work-protocol.md carries each role's own account, including the
Problems Encountered field. Read those first: they are the closest thing to a
first-hand incident report, and a problem that was logged and then ignored is a worse
finding than the problem itself.
Git history
Start with the retained work item's Release Manager entry to identify the merged PR and published release. Use the merged PR's recorded base and head commits to inspect the delivery commit range, and corroborate it with the release and CI history:
git log --oneline <pr-base>..<pr-head> # how often delivery work was redone
git log --format='%s' <pr-base>..<pr-head> | cut -d: -f1 | sort | uniq -cRepeated commits touching the same file, or a string of fix: commits after a
feat:, tell you where the work actually went.
Do not use origin/main..HEAD for a post-release documentation follow-up. At that
point the delivery commits are already on main, so that range contains only the
follow-up branch and can hide the cycle being reviewed. If the Release Manager entry,
merged PR, release, or CI record does not establish a fact, say the evidence is
unavailable rather than reconstructing it from memory.
CI
scripts/check-workflow-status.sh listWhat failed, and how late it failed. A failure caught in PR Validation that a role could have caught locally is an argument for moving the check earlier.
What this skill replaced
Retrospectives used to be driven by VS Code chat exports, parsed by
scripts/analyze-chat.py. Those exports do not exist outside VS Code, and the metrics
they produced (model usage, tool invocation counts, approval friction) measured the
harness rather than the workflow. The sources above measure the work.
Writing the finding
Every improvement opportunity needs three things or it is a wish:
- The evidence — which of the above, quoted.
- The change location — the file that would change.
- The verification — how you would know it worked.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

