speckit-opsmill-retrospect
Skill548 starsChanged 11 days agoApache-2.0View on GitHub
Run a session retrospective that surfaces context-management gaps and
In this repository54 other files it gives its agents.
- AGENTS.mdAGENTS.md
- backend/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- backend/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- analyzing-ci-flakinessSkill
- audit-docsSkill
- commitSkill
- creating-changelog-entriesSkill
- creating-issuesSkill
- creating-prdSkill
- grilling-ideasSkill
- harvesting-reviewSkill
- migrate-feature-pageSkill
- monitoring-pull-requestsSkill
- neo4j-cypher-guideSkill
- opsmill-dev-analyzing-bugsSkill
- opsmill-dev-fixing-bugsSkill
- opsmill-dev-test-driving-bugsSkill
- pre-ciSkill
- prSkill
- rebaseSkill
- reviewing-pull-requestsSkill
- speckit-agent-context-updateSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-critique-runSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-opsmill-autoSkill
- speckit-opsmill-extractSkill
- speckit-opsmill-implementSkill
- speckit-opsmill-prepSkill
- speckit-opsmill-summarySkill
- speckit-planSkill
- speckit-review-codeSkill
- speckit-review-commentsSkill
- speckit-review-errorsSkill
- speckit-review-runSkill
- speckit-review-simplifySkill
- speckit-review-testsSkill
- speckit-review-typesSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- upgrading-infrastructure-dependenciesSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 13 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 32
Never edit generated files.
- Very specific: line 33
Do not treat personal preferences as repo policy.
- Distinctive: line 40
Run git status --short to understand whether there are existing edits.
- Very specific: line 43
If it succeeds, record FEATURE_DIR and use FEATURE_DIR/retrospective.md as the report path.
- Very specific: line 44
If it fails or the project is not on a spec-kit feature branch, continue as an ad-hoc session and use …
- Distinctive: line 70
Prefer concrete findings over broad observations.
- Very specific: line 85
If a finding involves database schema or migration changes, GraphQL schema changes, new dependencies, CI/CD workflows, authentication, …
- Very specific: line 86
If a finding needs product or architecture ownership, prefer github-issue unless the user explicitly asks for a dedicated PR.
- Distinctive: line 87
If a finding is already fully covered by existing docs or instructions, do not include it as a finding.
- Distinctive: line 91
Before writing any files, present the retrospective in chat using this structure:
- Distinctive: line 144
If the report path already exists, append a numeric suffix rather than overwriting it.
- Distinctive: line 153
Wait for confirmation if the preview changes the original scope.
- Distinctive: line 155
Run relevant validation. For prompt, command, and Markdown-only changes, at minimum verify paths exist and the command can be discovered …
- Distinctive: line 160
Ask for explicit approval before creating a branch, committing, pushing, or opening a PR.
- Distinctive: line 161
If approved, use the repository's normal PR workflow.
- Distinctive: line 167
Create issues only after approval.
- Distinctive: line 172
Do not add local-only preferences to repo files unless the user explicitly reclassifies them as repo policy.
- Distinctive: line 176
After approved actions are complete, provide a brief summary:
≈ “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
User Input
$ARGUMENTSYou MUST consider the user input before proceeding (if not empty). Treat it as optional scope guidance, such as a focus area, a pasted transcript summary, or a preferred disposition.
Outline
Run a retrospective on the current agent session while the work is still fresh in context. The goal is to identify concrete improvements to the repository's context-management surface area: AGENTS.md, CLAUDE.md, .claude/settings.json, .agents/skills/, .agents/commands/, .specify/templates/, dev/knowledge/, dev/guides/, dev/guidelines/, dev/adr/, and product or architecture decisions that caused avoidable friction.
This command closes the loop from "the agent struggled with X" to "X is captured as an approved repo improvement, dedicated PR, GitHub issue, or local-only note."
Operating Constraints
- Stay read-only until the user approves the report and any disposition buckets. Do not edit files, commit, push, or create GitHub issues before approval.
- Present the full retrospective before taking action. Ask for explicit approval per disposition bucket:
fix-now,open-pr,github-issue, andlocal-only. - For
fix-now, present a diff preview or precise patch plan before writing files. Apply only the approved changes. - For
github-issue, defer to the existingcreating-issuesskill when available; if it is unavailable, usegh issue createonly after the user approves the exact issue content. - Respect
AGENTS.mdguardrails. Ask First topics, including database migrations, GraphQL schema changes, new dependencies, CI/CD workflow changes, and authentication or authorization changes, are never auto-applied. Route them toopen-prorgithub-issue. - Never edit generated files. If a finding points at generated output, identify the source template or generator instead.
- Do not treat personal preferences as repo policy. Use
local-onlyfor non-project-specific workflow preferences.
Phase 1: Resolve Session Context
- Identify the repository root and current branch:
- Run
git rev-parse --show-toplevel. - Run
git branch --show-current. - Run
git status --shortto understand whether there are existing edits.
- Run
- Determine whether the session is inside an active spec-kit feature:
- Try
.specify/scripts/bash/check-prerequisites.sh --json --paths-only. - If it succeeds, record
FEATURE_DIRand useFEATURE_DIR/retrospective.mdas the report path. - If it fails or the project is not on a spec-kit feature branch, continue as an ad-hoc session and use
.claude/retrospectives/YYYYMMDD-HHMMSS-<short-branch-or-session-slug>.mdas the report path.
- Try
- Load only the context needed to classify findings:
- Root
AGENTS.mdand any area-specificAGENTS.mdtouched this session. CLAUDE.mdand.claude/settings.jsonif present.- Relevant skill prompts in
.agents/skills/and commands in.agents/commands/. - Relevant spec-kit templates in
.specify/templates/. - Relevant
dev/knowledge/,dev/guides/,dev/guidelines/, ordev/adr/pages. - Current diff and recent commands from the conversation context.
- Root
Phase 2: Identify Findings
Review the current conversation and repository context for friction that was avoidable through better shared context. Organize findings into exactly these categories:
- Instructions / Configuration Gaps
- Missing, unclear, duplicated, or contradictory guidance in
AGENTS.md,CLAUDE.md,.claude/settings.json, skill prompts, commands, or spec-kit templates. - Required repo workflows that the agent had to infer or rediscover.
- Missing, unclear, duplicated, or contradictory guidance in
- Documentation Gaps
- Missing or stale content in
dev/knowledge/,dev/guides/,dev/guidelines/, ordev/adr/. - Docs that contradicted current code or left out required verification steps.
- Missing or stale content in
- Architectural Friction
- Product, architecture, or code choices that forced repeated workarounds.
- Candidates for ADRs, refactors, or product follow-up.
- Mistakes & Corrections
- Wrong turns taken during the session.
- The guardrail, instruction, template change, or test that would have prevented the mistake.
Prefer concrete findings over broad observations. Each finding must cite the session event or repository location that motivated it.
Phase 3: Assign Dispositions
For each finding, propose one disposition:
| Disposition | Use When | Action After Approval |
fix-now | Small, low-risk repo context updates that belong on the current branch and do not touch Ask First topics. | Show diff preview, then edit files only after approval. |
open-pr | Context or harness changes that should be reviewed separately from the current feature branch, or anything touching Ask First topics. | Draft a branch/PR plan. Do not branch, commit, push, or open a PR unless explicitly approved. |
github-issue | Larger work, ambiguous ownership, product/architecture debt, ADR candidates needing human authorship, or work outside current scope. | Use the creating-issues skill to draft each issue; create only after approval. |
local-only | Personal workflow preferences or notes that should not become repo policy. | Record only in approved local .specify/memory/report locations supported by the runtime. |
Disposition rules:
- If a finding involves database schema or migration changes, GraphQL schema changes, new dependencies, CI/CD workflows, authentication, authorization, or generated files, do not assign
fix-now. - If a finding needs product or architecture ownership, prefer
github-issueunless the user explicitly asks for a dedicated PR. - If a finding is already fully covered by existing docs or instructions, do not include it as a finding; mention it only in a brief "No action" note if helpful.
Phase 4: Produce Review Report
Before writing any files, present the retrospective in chat using this structure:
## Session Retrospective
**Scope**: <current feature, branch, or ad-hoc session>
**Proposed report path**: <path>
### Findings
| ID | Category | Evidence | Improvement | Disposition |
|----|----------|----------|-------------|-------------|
| R1 | Instructions / Configuration Gaps | <specific session event or file path> | <concrete change> | fix-now |
### Disposition Buckets
#### fix-now
- R1: <target file and change summary>
#### open-pr
- R2: <branch or PR scope>
#### github-issue
- R3: <issue title>
#### local-only
- R4: <memory/report note>
### Approval Request
Reply with one or more approved buckets, for example:
- `approve report only`
- `approve fix-now`
- `approve github-issue R3`
- `approve all except open-pr`The report must include concrete findings in all four categories. If a category genuinely has no findings, include the category with None found and a one-sentence reason.
Phase 5: Save Report
Save the retrospective report only after the user approves report only, a disposition bucket, or all.
Report path:
- Active spec-kit feature:
specs/<current-feature>/retrospective.md. - Ad-hoc session:
.claude/retrospectives/YYYYMMDD-HHMMSS-<short-branch-or-session-slug>.md.
If the report path already exists, append a numeric suffix rather than overwriting it.
Phase 6: Execute Approved Dispositions
Process only the buckets the user approved.
fix-now
- Show a diff preview or exact patch plan for the approved findings.
- Wait for confirmation if the preview changes the original scope.
- Apply edits with normal repository editing rules.
- Run relevant validation. For prompt, command, and Markdown-only changes, at minimum verify paths exist and the command can be discovered from the extension manifest and runtime command file. Run broader lint or tests when touched files are covered by existing automation.
open-pr
- Draft the proposed branch name, PR title, PR body summary, and changed file list.
- Ask for explicit approval before creating a branch, committing, pushing, or opening a PR.
- If approved, use the repository's normal PR workflow.
github-issue
- For each approved finding, invoke the
creating-issuesskill with the finding as source material. - Present the exact issue title/body/labels for approval.
- Create issues only after approval.
local-only
- Record the note only in runtime-supported local memory or in the approved retrospective report.
- Do not add local-only preferences to repo files unless the user explicitly reclassifies them as repo policy.
Completion
After approved actions are complete, provide a brief summary:
- Report path
- Actions taken
- Validation run
- Any remaining unapproved buckets
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.

